Şefim POS sistemini yapay zekâ istemcilerine Model Context Protocol (MCP) üzerinden bağlayan; yerel MSSQL veritabanı, güvenli işlem politikaları ve şifrelenmiş uygulama bilgisi üzerinde çalışan local-first yapay zekâ entegrasyonu.

Şefim POS için yerel yapay zekâ entegrasyonu

Şefim MCP AI, Şefim satış ve restoran otomasyon sistemini modern yapay zekâ istemcileriyle Model Context Protocol (MCP) üzerinden entegre etmek amacıyla geliştirdiğim bir MCP sunucusudur.

Projenin temel amacı, yapay zekânın yalnızca genel dil bilgisine dayanmak yerine Şefim'in gerçek veritabanı yapısını, iş kurallarını ve uygulama terminolojisini anlayarak kullanıcılarla etkileşime geçebilmesini sağlamaktır.

Sistem merkezi bir API veya uzak veritabanı gerektirmez. MCP sunucusu müşterinin bulunduğu ortamda çalışır ve yerel Microsoft SQL Server veritabanına doğrudan bağlanır.

MCP iletişimi stdio üzerinden gerçekleştirilir. Böylece Şefim veritabanının internete açılması veya harici bir MCP servisine aktarılması gerekmez.

MCP tabanlı mimari

Uygulamanın temel veri akışı şu şekilde tasarlanmıştır:

AI / MCP İstemcisi
        ↓
     stdio MCP
        ↓
   Şefim MCP Server
        ↓
Knowledge + Policy + Tools
        ↓
 Repository / SQL Service
        ↓
Local Microsoft SQL Server

Sunucu; yapay zekâ istemcisine ürünler, müşteriler, kullanıcılar, işlemler, masa grupları, kampanyalar ve raporlar gibi Şefim domain'leri üzerinde çalışabilecek MCP araçları sağlar.

Tam profilde sistem 182 MCP tool yayınlayabilir.

Yalnızca bilgi sorgulama ve raporlama gereken senaryolar için daha küçük bir core profile bulunur. Bu profilde tool sayısı 21'e düşürülerek model context maliyeti önemli ölçüde azaltılır.

Uygulama bilgisini anlayan Knowledge System

Bir veritabanındaki tablo ve kolon isimlerini bilmek, bir yapay zekânın uygulamanın nasıl çalıştığını gerçekten anlaması için yeterli değildir.

Bu nedenle projede Şefim'in;

iş kuralları,
tablo anlamları,
uygulama terminolojisi,
workflow'ları,
veri ilişkileri
ve domain bilgilerini

yapay zekâya sunan ayrı bir Knowledge System geliştirdim.

Knowledge belgeleri çalışma zamanında doğrudan Markdown olarak dağıtılmaz.

Belgeler build sürecinde paketlenerek AES-256-GCM ile şifrelenmiş bir knowledge.pack dosyasına dönüştürülür.

Runtime sırasında bu paket okunur ve ilgili bilgiler MCP knowledge araçları üzerinden modele kontrollü şekilde sunulur.

Türkçe odaklı bilgi arama

Knowledge sistemi yalnızca belge okumaktan ibaret değildir.

Belgeler bölümlere ayrılarak memory üzerinde bir retrieval index oluşturulur ve içerikler BM25 tabanlı arama algoritmasıyla aranır.

Türkçeye özel normalizasyon sayesinde;

Ürün
URUN
urun
ürünün
ürünler

gibi farklı kullanımlar aynı kavrama ulaşabilir.

Türkçenin eklemeli yapısı nedeniyle klasik bir stemmer yerine ortak kök/önek eşleşmeleri de kullanılmaktadır.

Bu sayede model tüm knowledge paketini context'e almak yerine yalnızca ihtiyaç duyduğu belge veya bölümü çağırabilir.

Schema Discovery

Şefim sürümleri arasında veritabanı şeması değişebileceği için yapay zekânın tablo yapısını tahmin etmesi yerine gerçek SQL Server metadata'sını inceleyebilmesi sağlandı.

Metadata katmanı SQL Server catalog bilgilerini kullanarak;

kolonları,
primary key'leri,
foreign key'leri
ve tablo ilişkilerini

dinamik olarak okuyabilir.

Ancak yapay zekâya bütün veritabanı sınırsız şekilde açılmaz.

MCP tarafındaki erişimler belgelenmiş ve izin verilen tablolar üzerinden kontrol edilir.

Güvenli SQL sorguları

Yapay zekânın gerektiğinde özel rapor sorguları oluşturabilmesi için read-only SQL desteği bulunmaktadır.

Bu sorgular çalıştırılmadan önce özel bir ReadOnlySqlGuard katmanından geçer.

Guard sistemi;

INSERT
UPDATE
DELETE
MERGE
EXEC
DDL komutları
birden fazla SQL statement
cross-database erişimi
sys.*
INFORMATION_SCHEMA
credential ve secret alanlarını

engelleyebilir.

Ad-hoc sorgularda döndürülebilecek sonuç sayısı da sınırlandırılmıştır.

Bu yapı veritabanı seviyesinde uygulanması gereken least privilege yaklaşımına ek bir güvenlik katmanı olarak çalışır.

Kritik işlemler için Operation Guard

Silme veya benzeri kritik operasyonların model tarafından yanlışlıkla zincirlenmesini azaltmak için server-side bir Operation Guard geliştirdim.

Kritik bir işlem için önce kısa ömürlü ve hedefe bağlı bir challenge oluşturulur.

Challenge;

yalnızca ilgili hedef için kullanılabilir,
tek kullanımlıktır,
yaklaşık iki dakika geçerlidir
ve yeniden kullanılamaz.

Bu yapı kullanıcı onayının yerine geçmez; model kaynaklı yanlış işlemlere karşı ek bir server-side güvenlik mekanizması sağlar.

Güvenlik odaklı Knowledge Packaging

Özel uygulama bilgisinin release artifact'lerine yanlışlıkla düz metin olarak girmemesi için build seviyesinde de kontroller bulunur.

Publish sırasında;

private Markdown dosyalarının artifact'e girmesi,
knowledge.pack dosyasının eksik olması,
plaintext knowledge içeriğinin publish çıktısında bulunması

otomatik olarak kontrol edilir.

Bu kontroller başarısız olduğunda build durdurulur.

Knowledge paketinin bütünlüğü AES-GCM authentication ile korunurken kaynak içeriği ayrıca fingerprint ile takip edilebilir.

Native AOT

Şefim MCP AI, .NET 10 Native AOT kullanılarak yayınlanabilir.

Projede;

Native AOT,
trimming,
self-contained deployment,
speed optimized compilation
ve deterministic build

özellikleri kullanılmaktadır.

Bu sayede hedef sistemde ayrıca .NET runtime kurulumu gerektirmeyen bağımsız executable'lar üretilebilir.

Cross-platform build sistemi

GitHub Actions release pipeline'ı üzerinden farklı mimariler için otomatik build ve paketleme yapılmaktadır.

Desteklenen ana hedefler:

Windows x64
Windows ARM64
Linux x64
Linux ARM64
macOS Intel
macOS Apple Silicon

şeklindedir.

Proje tanımında ayrıca Linux musl x64 runtime hedefi de bulunmaktadır.

MCP istemcileri

Kurulum ve yapılandırma sistemi farklı MCP istemcileriyle çalışabilecek şekilde tasarlanmıştır.

Bunlar arasında:

Claude Desktop
ChatGPT Desktop
Codex CLI

bulunmaktadır.

Windows kurulum sistemi mevcut Şefim kurulumunu tespit edebilir, bağlantı bilgilerini okuyabilir ve gerekli MCP istemci yapılandırmasını otomatik olarak oluşturabilir.

Mevcut MCP yapılandırmaları değiştirilirken diğer MCP sunucularının ve istemci ayarlarının korunmasına dikkat edilir.

Test ve CI/CD

Projede knowledge sistemi, SQL güvenliği ve kurulum altyapısı için otomatik testler bulunmaktadır.

Test kapsamına örnek olarak;

Knowledge packaging
Knowledge search
Knowledge security
Read-only SQL guard
Şefim installation detection
MCP client configuration
Setup paths

gibi alanlar dahildir.

GitHub Actions pipeline'ı test, Native AOT publish, payload doğrulama, installer oluşturma ve release artifact üretim süreçlerini otomatik olarak gerçekleştirir.

Sonuç

Şefim MCP AI ile amaçladığım şey yalnızca bir veritabanını yapay zekâya bağlamak değil.

Uygulamanın kendi terminolojisini ve iş mantığını anlayabilen, gerektiğinde gerçek database metadata'sına başvurabilen, minimum gerekli veriyi kullanan ve kritik işlemleri server-side politikalarla sınırlandırabilen bir AI entegrasyon katmanı oluşturmaktı.

Bu proje ile geleneksel bir masaüstü POS uygulaması, mevcut mimarisi değiştirilmeden modern MCP destekli yapay zekâ ekosistemine dahil edilebiliyor.

Teknolojiler

C#
.NET 10
Model Context Protocol (MCP)
Microsoft SQL Server
Microsoft.Extensions.Hosting
Native AOT
System.Text.Json
AES-256-GCM
SHA-256
BM25 Search
GitHub Actions
Qt Installer Framework
PowerShell
Bash
JSON-RPC
stdio

Platformlar

Windows x64
Windows ARM64
macOS Intel
macOS Apple Silicon
Linux x64
Linux ARM64
Linux musl x64

MCP istemci entegrasyonları:

Claude Desktop
ChatGPT Desktop
Codex CLI