workflow-core

MCP sunucularının iş akışı belgelerini okuyan, arayan, doğrulayan ve MCP kaynağı olarak yayımlayan Python kütüphanesi. Sunucu değildir: port dinlemez, araç yayımlamaz. Sunucular onu içe aktarır ve üç ayarla yapılandırır.

Durum (2026-09-30): dört tüketici sunucu motora bağlı ve kopyasız; yol haritasının beş fazından dördü geçti. Motor 0.5.4 (269 test, ruff temiz); dağıtım adı mcp-workflow-core, lisans Apache 2.0, PyPI'da 0.5.4.

Hangi sürümdeyim: paket sürümü 0.5.4. Kaynak pyproject.toml ([project] version); tests/test_surum.py bu satırı ona bağlar, çalışma anında workflow_core.__version__ aynı numarayı verir. Kuralların sürümü ayrıdır: anayasa 1.4.0.

Ne yapar

Bir sunucunun belge klasöründeki Markdown iş akışı belgelerini yönetir. Her belge bir üst bilgi bloğu (frontmatter) ve zorunlu bölümler taşır; motor bunları:

• listeler ve okur,
• arar (Türkçe harfleri katlayarak: büyük İ, aksanlı ve aksansız yazım aynı sonucu verir),
• doğrular (zorunlu alanlar, zorunlu bölümler, gövdede anılan araç adlarının çalışma anındaki kayıtta var olup olmadığı, bayatlık — last_verified: olculmedi beyanı bayatlık yerine bilinçli ölçümsüzlük sayılır —, scripts_used ile beyan edilen betik yollarının depoda gerçekten durup durmadığı),
• yazar, günceller ve siler (kuru çalıştırma ve arşivle),
• MCP kaynağı olarak yayımlar.

Motor belgeleri çalıştırmaz, okutur. Belge "makinenin yürüteceği kod" değil, "akıllı bir asistanın okuyacağı yönerge"dir; koşul, döngü ve karar asistanın işidir.

Kullanım, tüketici sunucuda:

from workflow_core import Config, Library

library = Library(Config.from_file("workflow.yaml"))  # docs_dir, tool_prefix, categories
library.search("devreye alma")                         # Türkçe katlamalı arama
library.validate(registered_tools=canli_arac_listesi, today="2026-08-22")
library.write("42-yeni-belge", icerik, dry_run=True)  # plan döner, disk değişmez
library.dispatch("get", {"id": "42-yeni-belge"})       # tek giriş: action + params

MCP kaynağı olarak yayın çerçeveye göre tek satır: workflow_core.adapters.gofastmcp ya da workflow_core.adapters.official_sdk içinden register(server, library). Onay kapısı motorda değil tüketici aracındadır; motor dry_run planını ve yıkıcı eylem işaretini (ACTIONS) verir.

Neden var

Aynı motor daha önce üç sunucuya kopyalanmıştı: toplam 1720 satır, paylaşılan satır sıfır. Düzeltmeler iki yönde de akmadı; bir kopyada yapılan iyileştirme ötekilere gitmedi, orijinaldeki düzeltme kopyalara gitmedi. Faz 0 ölçümü hiçbir kopyanın "en zengin" olmadığını gösterdi: doğru davranışlar üçüne dağılmıştı ve arama üçünde de Türkçe-güvenli değildi. Birleştirme tek kopyayı seçerek yapılamaz; bu yüzden motor tek yerde yazılıyor ve sunucular onu kütüphane olarak alıyor.

Tasarım ilkeleri

• Motor tek, yapılandırma çok. Sunucuya özel üç şey var: belge klasörünün yolu, araç-adı öneki, geçerli kategori listesi. Dördüncüsü gerektiğinde önce "bu gerçekten sunucuya mı özel" diye sorulur. Tanınmayan yapılandırma alanı reddedilir.
• Alan-özel if yok. Sunucuya özel davranış yapılandırma alanıyla çözülür; alan eklemek diff'te görünür, if görünmez.
• Hiçbir MCP çerçevesine bağlanmaz. Tüketiciler iki farklı çerçevede çalışıyor; motor ikisini de içe aktarmaz, kaynak kaydı çerçeveden bağımsız bir arayüzle sunulur.
• Sessiz düşüş yok. Yedek yola düşüş, kırpma ve yok sayma en az bir uyarı loglar.
• Yazma güvenlik zinciriyle. Kuru çalıştırma motorda, onay tüketici aracında; eski sürüm arşivlenir, yazma atomiktir, sonuç geri okunur. success: true kanıt değildir.
• Kopyalanmaz. Tüketiciler paketi düzenlenebilir kurulumla (pip install -e) alır. Düzeltme diske anında akar; çalışan sunucuya yeniden başlatmayla gelir.

Yapılandırma sözleşmesi (taslak)

Faz 1'de kesinleşir. Bugünkü niyet:

Bu üçünün dışındaki her şey ortak koddur.

Tüketici kılavuzu

Bir sunucuyu motora bağlamak beş adımdır; her adımın kanıtı yanında yazılı.

1. Kur. Dağıtım adı mcp-workflow-core (PyPI'daki workflow-core başka bir paketin; içe aktarma adı workflow_core aynı): pip install mcp-workflow-core, ya da aynı makinede kaynaktan düzenlenebilir kurulum pip install -e <workflow-core dizini>. Düzenlenebilir kurulum diske anında akar, çalışan sunucuya yeniden başlatmayla gelir (anayasa, bilinen tuzaklar). Bağımlılık satırına üst sınır yazın (<0.4). Jev refleks katmanı (workflow_core.jev: tipli hızlı kararlar + adım koşturucu) kullanılacaksa kurulum pip install mcp-workflow-core[jev] — pydantic yalnız bu grupla gelir, çekirdek motor bağımlılıksız kalır. Katmanın kanonik kuralları, güvenlik kapısı semantiği ve "belgeden adım üretilmez" sınırı: JEV.md.
2. Yapılandır. Sunucu köküne workflow.yaml: docs_dir, tool_prefix, categories. Dördüncü alan yazılırsa motor yüklenmez; kategori listesi boş olamaz.
3. Sar. Tek araç + action: library.dispatch(action, params). Araç açıklamasını ve yıkıcılık işaretini ACTIONS tablosundan üret. Onay kapısı sunucunun işidir: confirm verilmemişse write ve delete dry_run=True ile çağrılır ve plan döner, confirm=True ile gerçek yazma. Araç listesi canlı kayıttan registered_tools, kaynağı tool_source olarak verilir. Hata zarfı (ok, type) sarmalayıcıda; motor istisna fırlatır.
4. Yayımla. from workflow_core.adapters.<çerçeve> import register; register(server, library) somut listeyi ve workflow://{id} şablonunu birlikte kaydeder. Somut liste kayıt anının anlık görüntüsüdür: sonradan eklenen belge şablon adresle okunur, listeye sunucu yeniden başlatılınca girer. Bu bedel bilinçli (tasarım kılavuzu §4); yalnız somut liste kurulursa yeni belge hiç okunamaz.
5. Doğrula. Yeniden başlat, sonra canlı: büyük İ'li Türkçe sorgu sonuç döndürüyor mu, validate notunda araç listesinin kaynağı yazıyor mu, workflow://<kimlik> okunuyor mu, dry_run diske dokunmuyor mu. success: true kanıt değildir.

Ret bir karardır, hata değil. Motor yazmayı ya da silmeyi reddettiğinde istisna fırlatmaz; allowed, blocked_by, written / deleted taşıyan planı döndürür ve sonuca kendi hükmünü koyar. ok yalnız "diske yapıldı" demektir: kuru çalıştırmada ve rette daima false, gerçek koşuda geri okuma doğrulayınca true; planın geçip geçmeyeceği allowed alanında. Zarfı motorun alanlarından türetin, ok'u koşulsuz yazmayın; hangi sırayla yazarsanız yazın motorun değeri onaysız planı "yapıldı" göstermez. İlk bağlantıda reddedilen bir silme koşulsuz ok yüzünden başarılı görünmüştü (2026-08-25); 0.1.1 kuru çalıştırmada "yapılabilir" anlamında true yazınca üç sunucuda onaysız plan yapılmış göründü (2026-08-26), 0.2.0 bunu kapattı.

Eski motor dosyası bağlantıdan sonra silinir; kopya kalırsa çatallanma geri gelir. İlk doğrulamada yeni kurallar uyarı üretir (missing_verified_on, frontmatter içi yorum satırı); belge uyumu sunucunun işidir, sayılar Faz 1 planının SC-006 tablosunda.

Depo düzeni

workflow_core/            motor paketi: yapılandırma, belge modeli, arama, doğrulama, yazma, kaynak, dağıtıcı
  adapters/               çerçeveye dokunan tek yer; çerçeve başına bir dosya
tests/                    pytest: modül başına test + kapanış, sessizlik, adsız çıktı testleri
  korpus/, golden/        deneme belgeleri ve sorgu-beklenti seti
.sdd/                     süreç belgeleri: anayasa, yol haritası, görevler, şartnameler
  features/00N-*/         Faz 0 fark tablosu; Faz 1 şartname, plan, yetenek envanteri
_olcumler/                gerçek korpus ölçümleri (sürüm kontrolü dışında)
JEV.md                    Jev katmanının kanonik kural gövdesi; tüketiciler buna işaret eder
pyproject.toml            paket tanımı, sürümün tek kaynağı, ruff ayarı
.test-komutu              push öncesi kapının koştuğu test komutu

Geliştirme

Python 3.11 gerekir. Sanal ortam aç, paketi düzenlenebilir kur (tüketici sunucular da aynı komutla, kendi sanal ortamlarına kurar):

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"   # motor + pytest + ruff

python -m pytest tests -q              # testler (kaynak ağacından da koşar)
ruff check . ; ruff format --check .   # linter ve biçim
python .sdd/scripts/sdd.py durum       # aktif özellik, kapılar, sıradaki adım
python .sdd/scripts/sdd.py denetle     # belge düzeni denetimi
python .sdd/scripts/sdd.py sizinti     # ortama bağlı iz taraması

Push öncesi kapı (pre-push) testleri ve düzen denetimini kendisi koşar; kırmızı testle push yapılamaz.

İş akışı şartname odaklıdır: bir iş önce .sdd/ROADMAP.md'de durur, sdd yeni ile şartnamesi açılır, onaylanır, planı yazılır, sdd kontrol sıfır dönünce görevleri .sdd/TODO.md'ye düşer. Onay sohbette değil dosyada verilir.

Belgeler