diff --git a/kb/concepts/INDEX.md b/kb/concepts/INDEX.md index d7cd5c7..437700b 100644 --- a/kb/concepts/INDEX.md +++ b/kb/concepts/INDEX.md @@ -2,7 +2,7 @@ # kb/concepts/ - Index -79 page(s). Regenerated by `wikitool index rebuild`. +80 page(s). Regenerated by `wikitool index rebuild`. ## All @@ -42,7 +42,7 @@ | [[Implementation Spectrum]] | architecture | Modularer Einführungspfad für die Funktionen von LLM Wiki v2, vom minimal tragfähigen Wiki bis zur vollen Umsetzung mit Automatisierung und Governance. | 2026-08-29 | | [[Index Scaling]] | workflow | Skalierungsregeln für Indexseiten: Tabellenabschnitte ab 50 Einträgen teilen, ab 200 Seiten _meta/topic-map.md anlegen | 2026-08-29 | | [[Issue Label Scheme]] | decision | Zweiachsiges Pflicht-Labelschema fuer das Gitea-Board: prio/1..3 und size/XS..L, bewusst keine dritte Achse; die Regel liegt in instructions/dev/, weil sie keine ausgelieferte Instanz erreichen darf | 2026-08-31 | -| [[Iteration and Cost Limits]] | workflow | Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session\, Loop-Breaker bei 3 identischen Wiederholungen\, Slot-Erstattung bei abgelehntem Aufruf und ein seit 1.5.0 gemessenes Kalibrierungsband von 5-15 (einfach) bzw. 20-35 (komplex) Aufrufen | 2026-08-31 | +| [[Iteration and Cost Limits]] | workflow | Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen | 2026-09-02 | | [[KB Migration]] | workflow | Migration des KB-Inhalts entlang einer geordneten Versionskette; abgegrenzt gegen offene Instanz-Aktionen, die in den doctor-Check gehoeren statt in die Kette | 2026-08-31 | | [[KB Stack Versioning]] | decision | Semantische Versionierung des Wiki-Stacks: VERSION beschreibt die Maschinerie, Kompatibilitaet ist die linkeste Nicht-Null-Komponente, und drei getrennte Dateien trennen Maschinerie, Herkunft und Content-Form | 2026-08-30 | | [[Knowledge Compounding]] | workflow | Effekt, bei dem Wissen im Wiki an Wert gewinnt, weil jede neue Quelle an bestehende, untereinander verwiesene Seiten anknüpft und sie ergänzt. | 2026-08-29 | @@ -50,6 +50,7 @@ | [[Lint Workflow]] | workflow | Deterministischer Health-Check rund um wikitool lint; seit 1.7.2 maskiert es Code vor dem Notation-Match und zaehlt Zitat-Bloecke statt Zeilen | 2026-09-01 | | [[LLM Wiki Pattern]] | architecture | Methodik für persönliches Wissensmanagement, bei der ein LLM aus Rohquellen ein dauerhaftes Wiki aufbaut - Wissen wird kompiliert statt per RAG neu hergeleitet. | 2026-08-29 | | [[Mass-Update Gate]] | workflow | Mass-Update Gate: publish endet mit 42 (Freigabe durch den Menschen noetig) ab 10 gezaehlten Dateien; generierte Dateien und work/ werden committet\, aber seit 1.5.0 nicht gezaehlt; freigegeben per --confirm | 2026-09-01 | +| [[MCP-Leseserver]] | architecture | Zweiter Konsument von chemenu ueber MCP: search/types/describe_type/lint/status auf chemenu.api.Corpus, strukturell ohne Schreibpfad, jede Antwort trage einen Commit-Stempel. | 2026-09-02 | | [[Memory Lifecycle]] | architecture | Architektur des Wissenslebenszyklus mit Confidence Scoring, Supersession, Forgetting und Consolidation Tiers zur Pflege von Fakten über die Zeit. | 2026-08-29 | | [[Mesh Sync]] | pattern | Abgleichsmechanismus, der Beobachtungen paralleler Agenten in ein gemeinsames Wiki überführt; Last-Write-Wins mit Konflikterkennung und manuellem Eingriff. | 2026-08-29 | | [[Modbus]] | protocol | Industrielles Kommunikationsprotokoll von 1979 zur Anbindung speicherprogrammierbarer Steuerungen und Geräte über serielle oder TCP-Netze. | 2026-08-29 | @@ -60,7 +61,7 @@ | [[Personalization Plane]] | architecture | Schicht fuer Instanz-Identitaet: USER.md/SOUL.md werden als Template ausgeliefert, im Setup-Interview woertlich befuellt und vom doctor-Check auf fehlend wie unbefuellt geprueft | 2026-08-31 | | [[Privacy and Governance]] | workflow | Rahmenwerk zur Absicherung von Wiki-Inhalten über Datenfilterung beim Ingest, Audit-Trail-Protokollierung und umkehrbare Massenoperationen. | 2026-08-29 | | [[Procedural Memory]] | architecture | Langlebigste Speicherschicht für Abläufe, Muster, bewährte Vorgehensweisen und Rezepte, gewonnen aus wiederholten semantischen Beobachtungen. | 2026-08-29 | -| [[Publish-Remote Gate]] | workflow | Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; anders als die anderen Gates gibt es keinen Freigabe-Token. | 2026-09-01 | +| [[Publish-Remote Gate]] | workflow | Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; doctor benennt seit 2026-09-02 den Gate-Zustand statt nur die Dateiexistenz | 2026-09-02 | | [[Quality and Self-Correction]] | workflow | Automatische Qualitätssicherung für Wikis mit Inhaltsbewertung, Selbstheilung und Widerspruchserkennung. | 2026-08-29 | | [[Quality Scoring]] | pattern | Quantitative Bewertung aller vom LLM geschriebenen Inhalte nach struktureller Qualität, Vollständigkeit der Quellenangaben, Konsistenz mit dem Wiki und Themenabdeckung. | 2026-08-29 | | [[RAG]] | architecture | Architekturmuster, bei dem LLMs die Generierung um Dokumente aus einer Wissensbasis anreichern. | 2026-08-29 | diff --git a/kb/concepts/Iteration and Cost Limits.md b/kb/concepts/Iteration and Cost Limits.md index 4bd6ed7..e7a49a0 100644 --- a/kb/concepts/Iteration and Cost Limits.md +++ b/kb/concepts/Iteration and Cost Limits.md @@ -3,13 +3,13 @@ type: types/concept.md concept_type: workflow tags: [gate, safety, iteration-budget, loop-breaker] created: 2026-08-07 -modified: 2026-08-31 -related: [Mass-Update Gate, Anti-Cramming Heuristic, Index Scaling, wikitool, Structural Enforcement over Documented Rule] -sources: [Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31] +modified: 2026-09-02 +related: [Mass-Update Gate, Anti-Cramming Heuristic, Index Scaling, wikitool, Structural Enforcement over Documented Rule, MCP-Leseserver] +sources: [Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - MCP Read Server Implementation Session 2026-09-02] confidence: 0.88 confidence_base: 0.88 provenance: sourced -summary: Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session\, Loop-Breaker bei 3 identischen Wiederholungen\, Slot-Erstattung bei abgelehntem Aufruf und ein seit 1.5.0 gemessenes Kalibrierungsband von 5-15 (einfach) bzw. 20-35 (komplex) Aufrufen +summary: Im Code durchgesetzte Obergrenze von 60 wikitool-Aufrufen je Session, Loop-Breaker bei 3 identischen Wiederholungen, Slot-Erstattung, ein gemessenes Kalibrierungsband, und Retrieval sowie der MCP-Leseserver bleiben ausgenommen --- # Iteration and Cost Limits @@ -48,6 +48,11 @@ Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die - Einzelne, begrenzte Einmalvorgänge, bei denen die Aufrufen-Anzahl inhärent festgelegt ist (z. B. ein einzelner `new entity`-Aufruf) - das Gate wird dort immer noch gleichmäßig angewendet, wird aber im Wesentlichen nie ausgelöst. - Als Ersatz für das [[Mass-Update Gate]], das auf den *Schadensradius* eines `publish` (Dateien, die von einem einzelnen Push betroffen sind) begrenzt ist, nicht auf die *Iterationsmenge* über eine Sitzung - die beiden Gates beheben unterschiedliche Ausfallmodi und beide bleiben notwendig. +- Im [[MCP-Leseserver]]. Das Gate begrenzt eine Agenten-Session am unbemerkten Iterieren über den + Wiki-Zustand - deshalb ist Retrieval bereits generell ausgenommen (`SKIP_COMMANDS`) -, nicht + einen Nutzer, der oft sucht. Ein zu häufig suchender Nutzer ist ein Ressourcenproblem, das vor + den Serverprozess gehört (Rate Limiting), nicht in dieses Gate - beide zu vermischen würde es + zu einem Rate Limiter verwässern.[^s-mcp-read-server-implementation-session-2026-09-02] ## Verwandte Concepts @@ -63,6 +68,7 @@ Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die - **schützt:** [[Index Scaling]] - **implementiert durch:** [[wikitool]] - **wendet an:** [[Structural Enforcement over Documented Rule]] +- **nimmt aus:** [[MCP-Leseserver]] ## Siehe auch @@ -73,9 +79,11 @@ Eine hart in Code durchgesetzte Obergrenze für die Anzahl der Tool-Aufrufe, die - [[Source - LLM Improvements Production Agent Gaps 2026]] - [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]] - [[Structural Enforcement over Documented Rule]] +- [[MCP-Leseserver]] ## Fußnoten [^s-llm-improvements-production-agent-gaps-2026]: [[Source - LLM Improvements Production Agent Gaps 2026]] [^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]: [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]] [^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]] +[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]] diff --git a/kb/concepts/MCP-Leseserver.md b/kb/concepts/MCP-Leseserver.md new file mode 100644 index 0000000..886ea75 --- /dev/null +++ b/kb/concepts/MCP-Leseserver.md @@ -0,0 +1,108 @@ +--- +type: types/concept.md +concept_type: architecture +tags: [mcp, library-boundary, search, server] +created: 2026-09-02 +modified: 2026-09-02 +related: [wikitool, Publish-Remote Gate, Mass-Update Gate, Iteration and Cost Limits, Chemenu] +sources: [Source - MCP Read Server Implementation Session 2026-09-02] +confidence: 0.50 +confidence_base: 0.50 +provenance: sourced +summary: 'Zweiter Konsument von chemenu ueber MCP: search/types/describe_type/lint/status auf chemenu.api.Corpus, strukturell ohne Schreibpfad, jede Antwort trage einen Commit-Stempel.' +--- +# MCP-Leseserver + +**Typ:** Architecture + +## Definition + +Ein zweiter Konsument desselben Kerns, nicht ein zweites Programm: `tools/chemenu/mcp/` exponiert +`search`, `types`, `describe_type`, `lint` und `status` über MCP, indem es dieselben Funktionen +aufruft, die `wikitool` auch aufruft - vermittelt durch `chemenu.api.Corpus`, den In-Process- +Einstiegspunkt. Ein Golden-Test hält die Ausgaben beider Wege gegeneinander, statt darauf zu +vertrauen, dass sie übereinstimmen. + +## Kernpunkte + +- **Kein Schreibpfad, strukturell.** Weder der Server noch `chemenu.api` importiert etwas unter + `chemenu.commands` - `new`, `touch`, `xref`, `publish`, `migrate` sind aus diesem Prozess + heraus nicht erreichbar, statt aus einer Liste gefiltert zu werden. Ein Test importiert das + Servermodul in einem frischen Interpreter und prüft + `sys.modules`.[^s-mcp-read-server-implementation-session-2026-09-02] +- **Zwei Transports.** `stdio` zum Entwickeln und Testen ohne Netz; `streamable-http` für die + Auslieferung, der einzige, vor den sich ein HTTP-Reverse-Proxy setzen kann. `sse` ist über das + SDK erreichbar und wird bewusst nicht angeboten - der abgelöste Remote-Transport, jetzt darauf + zu bauen verschiebt den Wechsel nur. +- **Jede Antwort trägt den Commit, aus dem sie berechnet wurde** (`commit`, `as_of`). Ein + veralteter Checkout antwortet sonst selbstbewusst falsch. `null` heißt: der bediente Baum hat + uncommittete Änderungen, die Antwort entspricht keiner Revision. Der Stempel ist die Revision, + aus der die Seiten *tatsächlich* gelesen wurden, nicht die zum Zeitpunkt des Stempelns aktuelle + - ein Bug, der genau diesen Unterschied überging, wurde beim Schreiben des Golden-Tests selbst + gefunden und behoben.[^s-mcp-read-server-implementation-session-2026-09-02] +- **Telemetrie in den bedienten Baum wird beim Start verweigert**, nicht still umgeleitet. Der + Sync, der den Checkout aktuell hält (`git fetch && git reset --hard`), darf `reports/telemetry/` + wegräumen; ein Trace, der dort landet, wäre ein Verlust und eine stille Möglichkeit, den Baum + zu beschmutzen, dessen Sauberkeit der Korpus-Cache prüft. +- **Kein Iteration Budget Gate im Server.** Das Gate begrenzt eine Agenten-Session am unbemerkten + Iterieren über den Wiki-Zustand, nicht einen Nutzer, der oft sucht - Retrieval ist deshalb + bereits generell davon ausgenommen (siehe [[Iteration and Cost Limits]]). Rate Limiting gehört + stattdessen vor den Prozess, neben die Authentifizierung. +- **Authentifizierung ist Middleware, nicht Servercode.** Eine Traefik-ForwardAuth-Instanz + (Bearer-Token gegen SHA-256-Hashes) sitzt vor dem Prozess; nicht sauber authentifizierte + Zugriffe erreichen Python gar nicht erst. +- **Gemessen:** Korpus-Parse für 176 Seiten 265 ms → 54 ms (`CSafeLoader`), + `wikitool search` end-to-end 593 ms → 347 ms; die verbleibenden ~262 ms sind Modulimport und + entfallen im residenten Serverprozess, weil er ihn einmal pro Start statt pro Aufruf + zahlt.[^s-mcp-read-server-implementation-session-2026-09-02] + +## Beispiele + +- `search`/`types`/`describe_type`/`lint`/`status` als die fünf Tools - siehe + `tools/chemenu/mcp/server.py`. +- Der Korpus-Cache (`chemenu/corpus_cache.py`) hält einen Parse pro Commit und cacht nie einen + schmutzigen Arbeitsbaum - dieselbe Eigenschaft, die den Antwort-Stempel korrekt hält. +- `chemenu.api.Corpus`: nimmt einen Root, liefert exakt die `--json`-Formen der CLI, raised statt + zu exitieren. + +## Wann zu verwenden + +- Ein Konsument, der keine Shell auf der bedienenden Maschine ist, soll dieselben Fragen stellen + können wie ein Agent, der `wikitool` direkt aufruft. +- Mehrere gleichzeitige Leser eines Korpus, für die ein Prozess pro CLI-Aufruf (Modulimport, + Korpus-Parse) unnötigen Overhead bedeutet. + +## Wann NICHT zu verwenden + +- Als Ort für einen Schreibpfad - die Ingest-Queue (geplant, Issue #32) ist ein anderes Design + mit einer Quarantäne davor, nicht eine Erweiterung dieses Servers. +- Als Ersatz für den Iteration Budget Gate oder das Traefik-Rate-Limiting - beide bleiben + notwendig und leben an anderer Stelle. + +## Verwandte Concepts + +- [[Publish-Remote Gate]] +- [[Mass-Update Gate]] +- [[Iteration and Cost Limits]] + +## Fußnoten + +[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]] + +## Beziehungen + +- **implementiert:** [[wikitool]] +- **verwandt mit:** [[Publish-Remote Gate]] +- **verwandt mit:** [[Mass-Update Gate]] +- **ausgenommen von:** [[Iteration and Cost Limits]] +- **Teil von:** [[Chemenu]] + +## Siehe auch + +- [[wikitool]] +- [[Publish-Remote Gate]] +- [[Mass-Update Gate]] +- [[Iteration and Cost Limits]] +- [[Chemenu]] +- [[Source - MCP Read Server Implementation Session 2026-09-02]] + diff --git a/kb/concepts/Mass-Update Gate.md b/kb/concepts/Mass-Update Gate.md index f491ea9..e78a0fc 100644 --- a/kb/concepts/Mass-Update Gate.md +++ b/kb/concepts/Mass-Update Gate.md @@ -4,7 +4,7 @@ concept_type: workflow tags: [gate, safety, mass-update, confirmation] created: 2026-08-03 modified: 2026-09-01 -related: [Content Quality Control, wikitool, Iteration and Cost Limits, Structural Enforcement over Documented Rule, Bulk Operations, Publish-Remote Gate] +related: [Content Quality Control, wikitool, Iteration and Cost Limits, Structural Enforcement over Documented Rule, Bulk Operations, Publish-Remote Gate, MCP-Leseserver] sources: [Source - LLM Improvements Sonnet Analysis, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - LLM Improvements Codex Analysis] confidence: 0.88 confidence_base: 0.88 @@ -78,6 +78,7 @@ Das Mass-Update Gate ist ein Sicherheitsmechanismus, der die Ausführung pausier - **wendet an:** [[Structural Enforcement over Documented Rule]] - **grenzt ab gegen:** [[Bulk Operations]] - **verwandtes Gate:** [[Publish-Remote Gate]] +- **verwandt mit:** [[MCP-Leseserver]] ## Siehe auch @@ -88,6 +89,7 @@ Das Mass-Update Gate ist ein Sicherheitsmechanismus, der die Ausführung pausier - [[Structural Enforcement over Documented Rule]] - [[Bulk Operations]] - [[Publish-Remote Gate]] +- [[MCP-Leseserver]] ## Fußnoten diff --git a/kb/concepts/Publish-Remote Gate.md b/kb/concepts/Publish-Remote Gate.md index 57ab736..c7101a3 100644 --- a/kb/concepts/Publish-Remote Gate.md +++ b/kb/concepts/Publish-Remote Gate.md @@ -3,13 +3,13 @@ type: types/concept.md concept_type: workflow tags: [] created: 2026-09-01 -modified: 2026-09-01 -related: [Mass-Update Gate, Chemenu] -sources: [Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01] +modified: 2026-09-02 +related: [Mass-Update Gate, Chemenu, MCP-Leseserver] +sources: [Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02] confidence: 0.50 confidence_base: 0.70 provenance: sourced -summary: 'Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; anders als die anderen Gates gibt es keinen Freigabe-Token.' +summary: 'Drittes, im Code durchgesetztes Gate: publish bricht mit Exit 42 ab, wenn die aufgeloeste Push-URL nicht in einer optionalen, gitignoreten Allowlist steht; doctor benennt seit 2026-09-02 den Gate-Zustand statt nur die Dateiexistenz' --- # Publish-Remote Gate @@ -40,6 +40,12 @@ Remote lokal konfiguriert ist. ist wichtig: Ein Checkout ohne Beschränkungsbedarf soll nicht gezwungen sein, eine leere Konfigurationsdatei zu pflegen; eine beschädigte Datei darf aber nicht wie eine abwesende behandelt werden, sonst wird eine defekte Sicherung zu einer stillschweigend abgeschalteten. +- **`doctor` benennt seit 2026-09-02 den Gate-*Zustand*, nicht nur, ob die Datei existiert.** + Vorher meldete der Check nur die Anwesenheit von `.wikitool-remotes.json`; ob das + gleichbedeutend mit "scharf" ist, musste der Leser selbst schließen. Alle drei Ausgaben + beginnen jetzt mit `Gate armed:` bzw. `Gate not armed:` - der Ein-Remote-Fall ohne Allowlist + bleibt `OK` (er hat nichts zu schützen), sagt aber ausdrücklich, dass jedes Push-Ziel + durchkommt.[^s-mcp-read-server-implementation-session-2026-09-02] ## Wann zu verwenden @@ -88,11 +94,13 @@ Maschinerie ziehen) stehen in Gitea-Issue #30. ## Verwandte Concepts - [[Mass-Update Gate]] +- [[MCP-Leseserver]] ## Beziehungen - **gilt fuer:** [[Chemenu]] - **verwandtes Gate:** [[Mass-Update Gate]] +- **verwandt mit:** [[MCP-Leseserver]] ## Siehe auch @@ -100,7 +108,9 @@ Maschinerie ziehen) stehen in Gitea-Issue #30. - [[Chemenu]] - [[Mass-Update Gate]] - [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]] +- [[MCP-Leseserver]] ## Fußnoten [^s-private-instance-merge-correction-and-issue-30-session-2026-09-01]: [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]] +[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]] diff --git a/kb/entities/INDEX.md b/kb/entities/INDEX.md index cbca1f2..f10288d 100644 --- a/kb/entities/INDEX.md +++ b/kb/entities/INDEX.md @@ -19,7 +19,7 @@ |------|------|---------|----------------| | [[andybalholm-edl]] | project | Go-basierte EDL-Bibliothek für die Kommunikation mit eingebetteten Geräten. | 2026-08-29 | | [[BCDModule]] | project | Go-Modul, das die Entscheidungslogik für die Batterieladung umsetzt. | 2026-08-29 | -| [[Chemenu]] | project | Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich als Testbett und Demo unter AGPL-3.0/CC-BY-4.0 | 2026-09-01 | +| [[Chemenu]] | project | Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich, seit 2.4.0 mit einem MCP-Leseserver als zweitem Konsumenten | 2026-09-02 | | [[goresponsiveness]] | project | Go-Werkzeug zur Messung von Anwendungsleistung und Responsiveness. | 2026-08-29 | | [[ha-core]] | project | Kern-Integrationsbibliothek für Home-Assistant-E3DC-Systeme; stellt die E3DC-Kommunikationsprotokolle und den Home-Assistant-Integrationscode bereit. | 2026-08-29 | | [[hacs-e3dc]] | project | Home Assistant Custom Component zur Überwachung von E3DC-Energiesystemen. | 2026-08-29 | @@ -98,6 +98,6 @@ | [[Proton]] | tool | Wine-basierte Kompatibilitätsschicht von Valve; lässt Windows-Spiele über Steam unter Linux laufen, mit optimierter DirectX-Übersetzung. | 2026-08-29 | | [[qmd]] | tool | Lokale Suchmaschine für Markdown-Dateien mit hybrider BM25-Vektor-Suche und LLM-Reranking. | 2026-08-29 | | [[Steam]] | tool | Valves Plattform für digitalen Spielevertrieb und Spielebibliothek auf dem PC. | 2026-08-29 | -| [[wikitool]] | tool | Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 liegt es im Python-Paket chemenu, das Kommando heisst weiterhin wikitool | 2026-09-01 | +| [[wikitool]] | tool | Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar | 2026-09-02 | | [[Wine]] | tool | Kompatibilitätsschicht, die Windows-API-Aufrufe nach POSIX übersetzt und Windows-Anwendungen unter Linux, BSD und macOS ohne Virtualisierung oder Emulation ausführt. | 2026-08-29 | diff --git a/kb/entities/projects/Chemenu.md b/kb/entities/projects/Chemenu.md index 29f07ae..6b7560e 100644 --- a/kb/entities/projects/Chemenu.md +++ b/kb/entities/projects/Chemenu.md @@ -3,13 +3,13 @@ type: types/entity.md entity_type: project tags: [wiki, llm, knowledge-base] created: 2026-08-04 -modified: 2026-09-01 -related: [Personalization Plane, Issue Label Scheme, Optional Instance Context File, Delete Rather Than Anonymize, Dual Licensing by File Plan, Publish-Remote Gate] -sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01] +modified: 2026-09-02 +related: [Personalization Plane, Issue Label Scheme, Optional Instance Context File, Delete Rather Than Anonymize, Dual Licensing by File Plan, Publish-Remote Gate, MCP-Leseserver] +sources: [Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02] confidence: 0.90 confidence_base: 0.90 provenance: mixed -summary: Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich als Testbett und Demo unter AGPL-3.0/CC-BY-4.0 +summary: Deterministischer Wissenskompiler (raw/ -> kb/); seit 2.0.0 unter dem Namen Chemenu, seit 2026-09-01 oeffentlich, seit 2.4.0 mit einem MCP-Leseserver als zweitem Konsumenten --- # Chemenu @@ -63,6 +63,7 @@ Das Repository hat bereits ein deterministisches CLI, `tools/wikitool` (Python, - **wendet an:** [[Delete Rather Than Anonymize]] - **wendet an:** [[Dual Licensing by File Plan]] - **setzt um:** [[Publish-Remote Gate]] +- **enthaelt:** [[MCP-Leseserver]] ## Details @@ -142,6 +143,13 @@ Repositorys selbst und keine Aussagen aus einer Rohdatenquelle; der Änderungsda ## Historie +- 2026-09-02 - `2.2.3`-`2.4.1`: Issue #36s vierstufige Sequenz zum [[MCP-Leseserver]] umgesetzt + ([[Publish-Remote Gate]] scharf gestellt, Lesepfad gehärtet, Root-Auflösung von der Importzeit + gelöst, der Server selbst), dazu `INSTALL-MCP.md` und Issue #37 für das noch fehlende + Container-Image. Alle vier Sequenz-Issues geschlossen; #36 blieb offen, weil sein eigenes + Abschlusskriterium - ein Konsument, der nachweislich über die + Authentifizierungs-Middleware antwortet - erst mit #37 erfüllbar + ist.[^s-mcp-read-server-implementation-session-2026-09-02] - 2026-09-01 - `2.0.0` (Commit `9a7abe6`, 121 Dateien, 730 Tests grün): Rebranding von `llm-wiki-test1` auf **Chemenu** nach Gitea-Issue #3 - Repo-Rename, Produktname, Release-Artefakt (`chemenu-stack-.tar.gz`), Release-Feed, und das Python-Paket @@ -219,6 +227,7 @@ Repositorys selbst und keine Aussagen aus einer Rohdatenquelle; der Änderungsda - [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]] - [[Publish-Remote Gate]] - [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]] +- [[MCP-Leseserver]] ## Fußnoten @@ -230,3 +239,4 @@ Repositorys selbst und keine Aussagen aus einer Rohdatenquelle; der Änderungsda [^s-conversation-gate-counting-and-measured-calibration-session-2026-08-31]: [[Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31]] [^s-conversation-write-once-frontmatter-fields-and-touch-set-session-2026-08-31]: [[Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31]] [^s-conversation-comma-bug-budget-refund-and-lint-report-path-session-2026-08-31]: [[Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31]] +[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]] diff --git a/kb/entities/tools/wikitool.md b/kb/entities/tools/wikitool.md index 5d2d809..5004a40 100644 --- a/kb/entities/tools/wikitool.md +++ b/kb/entities/tools/wikitool.md @@ -3,13 +3,13 @@ type: types/entity.md entity_type: tool tags: [cli, automation, deterministic, wiki-management] created: 2026-08-03 -modified: 2026-09-01 -related: [Semantic Lint Automation, Session Orientation, Iteration and Cost Limits, KB Stack Versioning, KB Migration, Personalization Plane, Detect-Repair Asymmetry, Write-Once Frontmatter Fields, Denylist over Allowlist, Command Round-Trip Integrity, Green Suite Blind Spot, Ambient Environment Dependency, Structural Enforcement over Documented Rule, Optional Instance Context File] -sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis, Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01] +modified: 2026-09-02 +related: [Semantic Lint Automation, Session Orientation, Iteration and Cost Limits, KB Stack Versioning, KB Migration, Personalization Plane, Detect-Repair Asymmetry, Write-Once Frontmatter Fields, Denylist over Allowlist, Command Round-Trip Integrity, Green Suite Blind Spot, Ambient Environment Dependency, Structural Enforcement over Documented Rule, Optional Instance Context File, MCP-Leseserver] +sources: [Source - LLM Improvements Codex Analysis, Source - LLM Improvements Sonnet Analysis, Source - Copilot Skill Restructure Instructions, Source - Conversation - AGENTS.md Skill Restructuring Session 2026-08-04, Source - LLM Improvements Production Agent Gaps 2026, Source - Conversation - Versioning CI-CD and Content Migration Session 2026-08-30, Source - Conversation - Comma Bug Budget Refund and Lint Report Path Session 2026-08-31, Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31, Source - Conversation - Auto Mode and Tool Choice Session 2026-08-31, Source - Conversation - Write-Once Frontmatter Fields and touch --set Session 2026-08-31, Source - Conversation - Gate Counting and Measured Calibration Session 2026-08-31, Source - Conversation - Two Round-Trip Defects Found by an Ingest Session 2026-08-31, Source - Conversation - Hardening the Test Suite Against Silent Environment Dependencies Session 2026-08-31, Source - Conversation - ENVIRONMENT.md as an Optional Third Session-Level File Session 2026-08-31, 'Source - Public Release, Corpus Purge and History Squash Session 2026-09-01', Source - Publish-Remote Gate and Issue Triage Session 2026-09-01, Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01, Source - MCP Read Server Implementation Session 2026-09-02] confidence: 0.90 confidence_base: 0.90 provenance: sourced -summary: Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 liegt es im Python-Paket chemenu, das Kommando heisst weiterhin wikitool +summary: Deterministisches CLI fuer alle mechanischen Wiki-Operationen; seit 2.0.0 im Paket chemenu, seit 2.4.0 zusaetzlich als MCP-Leseserver erreichbar --- # wikitool @@ -51,6 +51,7 @@ Wie in der Codex-Analyse vermerkt, bietet wikitool die deterministische Grundlag - **zeigte:** [[Ambient Environment Dependency]] - **setzt um:** [[Structural Enforcement over Documented Rule]] - **setzt um:** [[Optional Instance Context File]] +- **implementiert:** [[MCP-Leseserver]] ## Befehle @@ -73,6 +74,9 @@ wikitool bietet die folgenden Befehlskategorien: Seitenkopf zurückgefaltet statt abgelehnt, und weil der Block immer zuletzt gerendert wird, richtet die erste Zitatoperation eine verrutschte Seite von selbst wieder ein[^s-conversation-two-round-trip-defects-found-by-an-ingest-session-2026-08-31] - **Abfrage:** `search` - Textsuche über `kb/` durch ein austauschbares Backend (`rg` heute), plus `--field`-Prädikate, die auf Frontmatter evaluiert werden (`entity_type=system`, `confidence>=0.8`, `tags=k8s`, `!source_url`). Ohne Text ist es eine reine strukturierte Abfrage. Schreibgeschützt und ausgenommen von der Iteration-Budget-Gate, da Abfrage das Lesen statt das Iterieren ist +- **MCP-Server:** `python -m chemenu.mcp` (`--transport stdio|streamable-http`) - kein + `wikitool`-Unterbefehl, sondern ein zweiter Einstiegspunkt über `chemenu.api.Corpus`, derselbe + Kern wie `search`/`types`/`lint`. Siehe [[MCP-Leseserver]] - **Indizierung:** `index rebuild` - regeneriert die `kb/index.md`-Map plus eine pro-Sammlung `INDEX.md`, wobei ein Bereich bei 50 Zeilen in seine eigene Shard aufgeteilt wird - **Herkunft:** `sources coverage`, `sources trace`, `sources rebuild-index` - **Protokollierung:** `log append`, `log status` @@ -147,6 +151,22 @@ ist[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. ## Historie +- 2026-09-02 - `2.2.3`-`2.4.1`: die vierstufige Sequenz aus Issue #36 (Publish-Remote-Gate + scharf, Lesepfad gehärtet, Root-Auflösung und Bibliotheksgrenze, [[MCP-Leseserver]]) plus + Menschendoku. `.wikitool-remotes.json` war trotz gegenteiliger Dokumentation nicht gesetzt - + angelegt und gegen ein erfundenes Ziel gegengeprüft (Exit 42). Sechs Lesepfad-Härtungen: + gelöschter ReDoS-Zweig in der Ranking-Funktion, ein 30-Sekunden-`rg`-Timeout, ein + YAML-Alias-Refusal (267 B → 672.603 Knoten reproduziert), `CSafeLoader` (265 ms → 54 ms), + gemeldetes statt geschlucktes kaputtes Frontmatter, ein Korpus-Cache, der nie einen + schmutzigen Arbeitsbaum cacht. `config.ROOT` und alle abgeleiteten Pfade waren zur Importzeit + gebunden - jetzt lazy aufgelöst (`$CHEMENU_ROOT` → Walk-up), mit einem eigenen + `config.reset()` gegen eine Falle, in die `monkeypatch`s eigener Teardown sonst zurückläuft. + Neuer typerloser Lesekern (`search/service.py`, `lint_core.py`, `types_core.py`) hinter + `chemenu.api.Corpus`, darüber der MCP-Server: `search`/`types`/`describe_type`/`lint`/`status`, + strukturell ohne Schreibpfad, jede Antwort mit Commit-Stempel. `wikitool search` end-to-end + 593 ms → 347 ms. Menschendoku `INSTALL-MCP.md`, ausgeliefert über `dist_cmd.ROOT_FILES`. + Siehe [[Publish-Remote Gate]], [[Mass-Update Gate]], + [[MCP-Leseserver]][^s-mcp-read-server-implementation-session-2026-09-02] - 2026-09-01 - `2.1.0`-`2.2.2`: Vorbereitung und Durchführung der Veröffentlichung. `dist export` bekommt `REQUIRED_ROOT_FILES` (fehlende Lizenzdateien lassen den Export scheitern statt still weiterzulaufen) und `find_leaks()` (strukturelle Prüfung des fertigen Export-Plans gegen @@ -267,6 +287,7 @@ ist[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. - [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]] - [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]] - [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]] +- [[MCP-Leseserver]] ## Fußnoten @@ -281,3 +302,4 @@ ist[^s-conversation-versioning-ci-cd-and-content-migration-session-2026-08-30]. [^s-llm-improvements-codex-analysis]: [[Source - LLM Improvements Codex Analysis]] [^s-public-release-corpus-purge-and-history-squash-session-2026-09-01]: [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]] [^s-publish-remote-gate-and-issue-triage-session-2026-09-01]: [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]] +[^s-mcp-read-server-implementation-session-2026-09-02]: [[Source - MCP Read Server Implementation Session 2026-09-02]] diff --git a/kb/index.md b/kb/index.md index a4feb21..3f9bae9 100644 --- a/kb/index.md +++ b/kb/index.md @@ -13,12 +13,12 @@ The page tables live in a generated `INDEX.md` inside each collection, linked be ## Statistics -- **Total Pages:** 176 +- **Total Pages:** 178 - **Comparisons:** 1 -- **Concepts:** 79 +- **Concepts:** 80 - **Entities:** 72 -- **Sources:** 24 -- **Last Updated:** 2026-09-01 +- **Sources:** 25 +- **Last Updated:** 2026-09-02 --- @@ -27,9 +27,9 @@ The page tables live in a generated `INDEX.md` inside each collection, linked be | Collection | Pages | Index | |------------|------:|-------| | `comparisons/` | 1 | [comparisons/INDEX.md](comparisons/INDEX.md) | -| `concepts/` | 79 | [concepts/INDEX.md](concepts/INDEX.md) | +| `concepts/` | 80 | [concepts/INDEX.md](concepts/INDEX.md) | | `entities/` | 72 | [entities/INDEX.md](entities/INDEX.md) | -| `sources/` | 24 | [sources/INDEX.md](sources/INDEX.md) | +| `sources/` | 25 | [sources/INDEX.md](sources/INDEX.md) | ### entities/ diff --git a/kb/log.md b/kb/log.md index 2d2dcd3..1b98e18 100644 --- a/kb/log.md +++ b/kb/log.md @@ -73,3 +73,9 @@ Source-Seite angelegt, neue Concept-Seite Publish-Remote Gate, wikitool-Historie Source-Seite angelegt, Publish-Remote-Gate-Seite um die gemessene Merge-Semantik erweitert, quer verlinkt. --- + +## [2026-09-02] ingest | MCP Read Server Implementation Session 2026-09-02 + +Source-Seite und neues Concept MCP-Leseserver angelegt; wikitool, Chemenu, Publish-Remote Gate und Iteration and Cost Limits aktualisiert. Deckt Issue #36s Sequenz (#34/#33/#31/#19), INSTALL-MCP.md und Issue #37 ab. + +--- diff --git a/kb/provenance.md b/kb/provenance.md index 0da829d..b0e981b 100644 --- a/kb/provenance.md +++ b/kb/provenance.md @@ -8,8 +8,8 @@ inline `[^cite-id]` footnote). ## Coverage Summary -- **Total raw files:** 24 -- **Covered:** 24 +- **Total raw files:** 25 +- **Covered:** 25 - **Uncovered:** 0 --- @@ -71,6 +71,11 @@ inline `[^cite-id]` footnote). - Covered by: [[Source - Conversation - Issue Triage Labels and TODO Retirement Session 2026-08-31]] - Cited by: [[Chemenu]], [[Detect-Repair Asymmetry]], [[Gitea]], [[Gitea Actions]], [[Gitea MCP Server]], [[Issue Label Scheme]], [[KB Stack Versioning]], [[wikitool]] +### `raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md` + +- Covered by: [[Source - MCP Read Server Implementation Session 2026-09-02]] + - Cited by: [[Chemenu]], [[Iteration and Cost Limits]], [[MCP-Leseserver]], [[Publish-Remote Gate]], [[wikitool]] + ### `raw/notes/Conversation Transcript - Nightly Drift-Check Workflow and doctor's Bootstrap Gap Session 2026-08-31.md` - Covered by: [[Source - Conversation - Nightly Drift-Check Workflow and doctor's Bootstrap Gap Session 2026-08-31]] diff --git a/kb/sources/INDEX.md b/kb/sources/INDEX.md index aef468d..be3f616 100644 --- a/kb/sources/INDEX.md +++ b/kb/sources/INDEX.md @@ -2,7 +2,7 @@ # kb/sources/ - Index -24 page(s). Regenerated by `wikitool index rebuild`. +25 page(s). Regenerated by `wikitool index rebuild`. ## All @@ -28,6 +28,7 @@ | [[Source - LLM Improvements Sonnet Analysis]] | notes | Sonnet-Analyse, die AGENTS.md und wikitool mit Farzas Gist und awesome-llm-wiki vergleicht und die Codex-Analyse um konkrete Empfehlungen zu Qualitätsschwellen, Stilrichtlinie, Auditrhythmus und Skalierung ergänzt | 2026-08-03 | | [[Source - LLM Wiki Pattern]] | article | Grundlegendes Muster für persönliche Wissensbasen mit LLMs: ein dauerhaftes Wiki schrittweise pflegen, statt es aus den Quellen neu herzuleiten. | 2026-07-26 | | [[Source - LLM Wiki v2]] | article | Erweitertes LLM-Wiki-Muster mit Praxiserfahrungen aus agentmemory zu Memory Lifecycle, Confidence Scoring, Wissensgraph und Automatisierung. | 2026-07-26 | +| [[Source - MCP Read Server Implementation Session 2026-09-02]] | notes | Sitzung, die die Sequenz aus Issue #36 umsetzt: Publish-Remote Gate scharf, Lesepfad gehaertet, Root-Aufloesung und Bibliotheksgrenze gezogen, MCP-Leseserver gebaut - vier Versionsstufen 2.2.3 bis 2.4.0, dazu INSTALL-MCP.md und Issue #37. | 2026-09-02 | | [[Source - Private-Instance Merge Correction and Issue 30 Session 2026-09-01]] | notes | Sitzung, die eine ungeprueft niedergeschriebene Merge-Behauptung in private-instance.md durch einen empirischen Test widerlegt, die Prozedur korrigiert (2.2.1) und Issue #30 mit einem getesteten Skript sowie zwei Architekturvorschlaegen anlegt. | 2026-09-01 | | [[Source - Public Release, Corpus Purge and History Squash Session 2026-09-01]] | notes | Sitzung, die den Chemenu-Stack von einer privaten Testinstanz in ein oeffentliches Repo ueberfuehrt: Korpus geloescht statt anonymisiert, Git-History auf einen Commit gesquashed, AGPL-3.0/CC-BY-4.0-Dual-Lizenz gewaehlt, dist export um einen Leak-Canary gehaertet. | 2026-09-01 | | [[Source - Publish-Remote Gate and Issue Triage Session 2026-09-01]] | notes | Sitzung, die ein drittes, Token-loses Gate fuer publish baut, instructions/private-instance.md schreibt, sechs Gitea-Issues auf den Rename und die neue Architektur nachzieht und die Actions-Run-Historie entfernen laesst. | 2026-09-01 | diff --git a/kb/sources/Source - MCP Read Server Implementation Session 2026-09-02.md b/kb/sources/Source - MCP Read Server Implementation Session 2026-09-02.md new file mode 100644 index 0000000..6ba7b91 --- /dev/null +++ b/kb/sources/Source - MCP Read Server Implementation Session 2026-09-02.md @@ -0,0 +1,100 @@ +--- +type: types/source.md +source_type: notes +author: Torben +raw_files: [raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md] +source_language: de +date: 2026-09-02 +tags: [] +entities: [wikitool, Chemenu] +concepts: [Publish-Remote Gate, Mass-Update Gate, Iteration and Cost Limits, MCP-Leseserver] +summary: 'Sitzung, die die Sequenz aus Issue #36 umsetzt: Publish-Remote Gate scharf, Lesepfad gehaertet, Root-Aufloesung und Bibliotheksgrenze gezogen, MCP-Leseserver gebaut - vier Versionsstufen 2.2.3 bis 2.4.0, dazu INSTALL-MCP.md und Issue #37.' +--- +# Source: MCP Read Server Implementation Session 2026-09-02 + +**Autor:** Torben +**Datum:** 2026-09-02 +**Raw-Dateien:** raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md +**Typ:** Notes + +## Zusammenfassung + +Diese Sitzung arbeitet die vierstufige Sequenz aus Issue #36 ab, dem Sammel-Issue für den Weg +zum MCP-Leseserver: #34 (Publish-Remote-Gate scharf stellen), #33 (Lesepfad vor der Exposition +härten), #31 (Root-Auflösung von der Importzeit lösen und eine Bibliotheksgrenze ziehen), #19 +(der Leseserver selbst). Jeder Schritt endet mit einem Versions-Bump und einem Testlauf; die +Reihenfolge folgt dem Master-Issue, weil #33 dieselben Dateien anfasst, die #31 strukturell +umbaut, und #31 die Grenze liefert, auf der #19 aufsetzt. + +`.wikitool-remotes.json` fehlte in diesem Checkout trotz Dokumentation, die das Gegenteil +behauptete - angelegt und gegen ein erfundenes Ziel gegengeprüft (Exit 42). Der Lesepfad bekam +sechs Fixes gegen einen 267-Byte-YAML-Alias, der zu 672.603 Knoten expandiert, gegen einen +ReDoS-Zweig in der Ranking-Funktion, einen fehlenden Subprozess-Timeout, und einen Korpus-Cache, +der nie einen schmutzigen Arbeitsbaum cacht. `config.ROOT` und alle abgeleiteten Pfade waren zur +Importzeit gebunden; die Auflösung ist jetzt lazy (`CHEMENU_ROOT` → Walk-up), und der reine +Lesekern (`search/service.py`, `lint_core.py`, `types_core.py`) importiert kein `typer` mehr. +Der MCP-Server (`tools/chemenu/mcp/`) exponiert `search`/`types`/`describe_type`/`lint`/`status` +über `chemenu.api.Corpus` - strukturell ohne Schreibpfad, mit Commit-Stempel auf jeder Antwort +und einer Startverweigerung, falls Telemetrie in den bedienten Baum schreiben würde. + +Nach Freigabe des 37-Datei-Changesets (Mass-Update-Gate, Token `46442f4419c1`) folgten +`INSTALL-MCP.md` für Menschen, ein Verweis auf die separate Traefik-ForwardAuth-Middleware +(`gitea-mcp-forward-auth`), und Issue #37 für das noch fehlende Container-Image - mit den +konkreten CI-Vorlagen aus `gitea-mcp-forward-auth` (Registry-Push) und `gitea-mcp` +(Dockerfile-Form, aber DockerHub statt der eigenen Registry). Alle vier Sequenz-Issues wurden +geschlossen, #36 blieb offen, weil sein eigenes Abschlusskriterium - ein Konsument, der +nachweislich über die Middleware antwortet - erst mit #37 erfüllbar ist. + +## Kernaussagen + +- Gemessen: Korpus-Parse 265 ms → 54 ms (`CSafeLoader`), `wikitool search` end-to-end + 593 ms → 347 ms; die verbleibenden ~262 ms sind Modulimport und entfallen erst im residenten + MCP-Prozess. +- Der ReDoS-Zweig (`_contains` mit `re.search` gegen nutzergesteuerten Regex) wurde gelöscht, + nicht begrenzt - `rg` wendet das Muster ohnehin mit einer linearen Engine an, bevor die + Funktion je läuft. +- `monkeypatch.setattr(config, "ROOT", ...)` baute nach der lazy-Auflösung die stale Bindung + beim Teardown wieder auf, weil es den *aufgelösten* alten Wert zurückschreibt - `config.reset()` + musste dazukommen, in derselben autouse-Fixture, die das Problem eine Ebene höher (Umgebungsvariablen) + bereits kannte. +- Der MCP-Server hat keinen Schreibpfad, weil `chemenu.api` nichts unter `chemenu.commands` + importiert - nicht, weil eine Liste gefiltert wird. Ein Test importiert das Servermodul in + einem frischen Interpreter und prüft `sys.modules`. +- Ein Stempel-Bug wurde beim Schreiben des Golden-Tests selbst gefunden: `_stamp()` fragte nach + der *aktuellen* statt der beim Laden tatsächlich gelesenen Revision und hätte bei einem + minimal verzögerten zweiten Zugriff `commit: null` auf einem sauberen Baum liefern können. +- `gitea-mcp` ist als Registry-Vorlage ungeeignet - sein Release-Workflow pusht nach DockerHub + (Fork des Upstream), nicht in die eigene Gitea-Registry. + +## Aufgaben + +- [x] #34, #33, #31, #19 umgesetzt und mit Abschlusskommentar geschlossen +- [x] `INSTALL-MCP.md` geschrieben, in `INSTALL.md`/`README.md` verlinkt, in `dist export` aufgenommen +- [x] Issue #37 (Container-Image) angelegt, mit neun offenen Entscheidungen benannt +- [ ] #37 selbst umsetzen +- [ ] #36 schließen, sobald #37 den Middleware-Nachweis liefert +- [ ] #23 (Env-Var-Erzwingung) - `CHEMENU_ROOT` wurde von Hand in `_WIKITOOL_ENV` eingetragen +- [ ] `kb/entities/tools/qmd.md` - falsche Sprachangabe, in dieser Sitzung nur vermerkt, Fix in + separater Transkript-Sitzung + +## Nicht übernommen + +- Der vollständige Wortlaut der geprüften Docstrings, Kommentare und Testfälle - das Transkript + benennt Dateien und die tragenden Eigenschaften, der Code selbst ist die Quelle. +- Die exakten neun offenen Entscheidungspunkte aus Issue #37 (Korpus im Image vs. Volume, + Basis-Image, Healthcheck etc.) - dort bereits vollständig dokumentiert, hier nicht dupliziert. +- Der Wortlaut der abgerufenen READMEs von `gitea-mcp-forward-auth` und `gitea-mcp` - nur die + für die Entscheidung relevanten Fakten (Config-Variablen, Workflow-Form, Registry-Ziel) + wurden übernommen. + +## Verwandte Entities + +- [[wikitool]] +- [[Chemenu]] + +## Verwandte Concepts + +- [[Publish-Remote Gate]] +- [[Mass-Update Gate]] +- [[Iteration and Cost Limits]] +- [[MCP-Leseserver]] diff --git a/raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md b/raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md new file mode 100644 index 0000000..c2c0c34 --- /dev/null +++ b/raw/notes/Conversation Transcript - MCP Read Server Implementation Session 2026-09-02.md @@ -0,0 +1,245 @@ +# Conversation Transcript - MCP Read Server Implementation Session + +> Source: Claude Code session (`claude-opus-5`), chemenu workspace +> Collected: 2026-09-02 +> Participant: Torben +> Fidelity: **faithful summary transcript, not a verbatim log.** Torben's instructions are +> quoted verbatim; the assistant's design reasoning, code, and file contents are condensed to +> what a later reader needs to find the artifact - the artifacts themselves are the code, not +> this transcript. Command outputs shown (test counts, timings, the Mass-Update Gate's printed +> file list, gate refusal messages) are real, copied from the session. No credentials appeared. +> No subagents were used - all work in this transcript is first-hand. +> One of two transcripts cut from this session; the other covers fixing `kb/entities/tools/qmd.md`, +> a documentation defect noted but not fixed during this one. + +Covers implementing the four-issue sequence held by #36 (the master issue for "path to the MCP +read server"): #34 (arm the Publish-Remote Gate), #33 (harden the read path), #31 (root +resolution + library boundary), #19 (the MCP server itself), plus the human-facing +`INSTALL-MCP.md` and filing #37 (the container-image follow-up) that #19's closure surfaced as +still missing. Four version bumps in sequence: 2.2.3, 2.2.4, 2.3.0, 2.4.0, then 2.4.1 for the +documentation follow-up. All five touched issues (#34, #33, #31, #19, #36) got closing comments; +#36 was left open pending #37. + +--- + +## Turn 1 - `/stack-dev implementiere #36` + +The `stack-dev` skill loaded, switching the session into tool-development rules (ordinary +software-engineering judgment on `tools/`, `types/`, `instructions/` - no source-binding, no +`raw/` citation needed for code). + +Read issue #36 (the master issue) via `gitea-mcp`. It holds no implementation itself - a +sequence table (#34 → #33 → #31 → #19), a table of platform/auth/transport decisions already +made and closed to debate, a measured baseline (593 ms per `wikitool search`, broken down: +262 ms module import, 274 ms corpus parse, 7 ms ripgrep), ten verified findings backing the +design, and an explicit "not in scope" list (Go, deployment details, a write path, #15's +research capability). Read #34, #33, #31, #19 in full including comments to get the acceptance +criteria and the reasoning behind each. + +Worked the sequence in order, starting a session-scoped `WIKITOOL_SESSION_ID`. + +**#34 - Publish-Remote Gate.** `.wikitool-remotes.json` did not exist in this checkout; absence +means unrestricted per `git_publish.read_allowed_push_urls()`. Created it with `origin`'s exact +push URL as the sole allowed target. Counter-checked by adding a second git remote to a made-up +URL and running `publish --remote gatecheck`: refused with **exit 42**, working tree untouched, +before any fetch. Remote removed afterward. + +`doctor`'s `check_publish_remotes()` reported only whether the *file* existed, not whether the +gate was actually armed. Rewrote its three outcome messages to lead with `Gate armed:` / +`Gate not armed:` explicitly - the single-remote-no-file case stays `OK` (nothing to protect, +and a FAIL would make the file mandatory through the back door) but now says outright that every +push target passes. The check had **no tests**; added three, one per state. + +Bumped `--patch` → **2.2.3**. + +**#33 - Harden the read path.** Six findings, each addressed with a regression: + +1. *ReDoS.* `search/ripgrep.py:_contains` passed `query.regex` to `re.search`. Deleted the + branch entirely rather than bounding it - `rg` already applies the pattern with a linear + engine before this function runs, so nothing is lost except the extra title/summary ranking + boost for a non-literal pattern (and summary/H1 lines are themselves counted by `rg`). + Regression test asserts both the timing (`< 0.5s` against `(\w+\s?)+$`) and the return value, + because a bound alone would pass with a merely-faster engine. +2. *No subprocess timeout.* Added `RIPGREP_TIMEOUT_SECONDS = 30.0`; `TimeoutExpired` translates + to the existing `RipgrepFailed` path. +3. *YAML aliases.* Frontmatter has no legitimate use for anchors/aliases, so they are refused + outright rather than budgeted, checked on the streaming *event* parse (`yaml.parse`) so the + check itself never triggers the expansion it is checking for - `*` is a necessary character + in any alias node, so its absence proves absence with zero parse cost. Constructed a + reproduction: 267 bytes of nested aliases compose into 672,603 nodes on traversal at + constant (0.2 ms) parse time, growth 9^n with nesting depth. Added a 64 KiB frontmatter size + limit and a `RecursionError` catch (PyYAML composes recursively; deep nesting is not a + `YAMLError`). +4. *`CSafeLoader` unused.* Switched to it with a `SafeLoader` fallback. Measured over this + corpus (176 pages, best of 5): **265 ms → 54 ms**. +5. *Silent frontmatter loss.* Decided: the read path now *reports* rather than swallows. + Unparseable YAML still degrades to `{}` for bulk operations, but the reason travels with it + (`Page.frontmatter_error`, set by a single parser shared between `read_page()` and + `frontmatter_error()` - previously two separate `safe_load` call sites that could describe + the same broken file differently). `search --json` now always carries an `unreadable` list + of `{path, reason}`; the table form writes the same lines to stderr. Added `read_page_strict()` + for the future ingest-quarantine path (#32), which must stop on unparseable input rather than + empty it. +6. *Corpus reparse per call.* New `chemenu/corpus_cache.py`: a `CorpusCache` object a caller + *holds* (not a module-global switch). The CLI holds none and is unaffected. Correctness + property, not just speed: **a dirty working tree is never cached** - if git cannot answer + whether the tree is clean, it is treated as dirty. `wikitool search` end-to-end (best of 5): + **593 ms → 347 ms**. + +Bumped `--patch` → **2.2.4**. + +**#31 - Root resolution + library boundary.** `config.ROOT` and everything derived from it were +Python module constants, bound at import time from `Path(__file__).resolve().parents[2]` - so +`monkeypatch.setattr(config, "ROOT", tmp_path)` repointed `ROOT` but left `KB_DIR`/`RAW_DIR` +aimed at the real checkout, the exact failure class `raw_dir`'s own fixture docstring already +warned about one layer up. + +Rewrote `config.py`: `resolve_root()` by precedence (explicit argument → `$CHEMENU_ROOT` → +walk-up, the walk-up staying default so `tools/wikitool` is unaffected), and every derived path +resolved on *attribute access* via module `__getattr__` (PEP 562) rather than stored - so an +assignment onto `ROOT` (test or otherwise) is honored by every path under it, live. This +surfaced a subtler bug while fixing the first one: `monkeypatch`'s own undo mechanism reads the +old value (which resolves it) and writes it back as a real attribute on teardown, recreating the +stale binding the rewrite was meant to eliminate. Added `config.reset()`, called by the autouse +hermetic-environment fixture on both setup and teardown. + +Split the CLI-coupled command modules into a pure core + thin adapter, three times over: +`search/service.py`, `lint_core.py`, `types_core.py` - none of them import `typer` or `rich`. +`commands/search.py`, `commands/lint.py`, `commands/types_cmd.py` became the terminal adapters, +re-exporting the same names so no existing import breaks. + +New `chemenu/errors.py`: `ChemenuError` → `ValidationError` (also inherits `ValueError`, since +`PredicateError` already was one and callers catch it that way) / `BackendError`. +`PredicateError`, `FrontmatterError`, `UnknownBackend`, `RipgrepMissing`, `RipgrepFailed` moved +under this hierarchy. + +New `chemenu/api.py`: `Corpus` class, the in-process entry point - takes a root, returns exactly +the CLI's `--json` shapes, raises instead of exiting, stamps every response with `commit`/ +`as_of`. Wrote the acceptance test by monkeypatching `Path.read_text`/`Path.rglob` to fail on any +access under the real checkout root while a foreign root is set - this test could not have +passed before the lazy-resolution rewrite. + +Two more accidental dependencies surfaced and were fixed: `TypeResolver.repo_root` was also +import-bound (fixed the same way, with `config.rooted()` as a process-wide context manager for +callers that reach `config` directly rather than taking a root argument - and `use_shipped_type_specs()` +added to the test fixtures that had been relying on it silently); and `search/registry.resolve()` +did not pass `kb_dir`/`root` through to the backend, so a caller pointing `run_search` at a +foreign corpus could still have `RipgrepBackend` read `config.KB_DIR` underneath it. + +Bumped `--minor` → **2.3.0** (new capability, backward-compatible). + +**#19 - MCP read server.** New package `tools/chemenu/mcp/` (`server.py`, `__main__.py`). +Installed the `mcp` SDK (`mcp>=2.0`, discovered mid-session that this pulled in the v2 API - +`FastMCP` renamed to `MCPServer`, imported from `mcp.server.mcpserver`). Five tools over +`chemenu.api.Corpus`: `search`, `types`, `describe_type`, `lint`, `status` (`status` is +server-composed, not a wrapper - there is no `wikitool status` command to wrap). No write tool, +structurally: neither the server module nor `chemenu.api` imports anything under +`chemenu.commands`. + +Both transports built and smoke-tested end-to-end against the real 176-page corpus: `stdio` via +a hand-written MCP client script, and `streamable-http` (host/port bound explicitly - the +default binds loopback, wrong for a container behind a proxy) via a subprocess + HTTP client +round-trip. `sse` deliberately not offered (superseded transport). + +`ChemenuError` translated to the SDK's `ToolError` at the tool-call boundary (a deliberate +refusal whose message reaches the caller) rather than left to become an `UnexpectedToolError` +(a crash whose message stays server-side). + +Found and fixed a stamping bug while writing the golden test: `_stamp()` was asking the cache for +the *current* revision after the load had already happened, so a caller with a perfectly clean +tree could see `"commit": null` if the cache's cached revision lagged. Fixed by threading the +revision the load actually returned through to the stamp. + +Wrote `tools/chemenu/tests/test_mcp_server.py`: the golden test runs `wikitool ... --json` as a +subprocess against the same fixture tree (via `$CHEMENU_ROOT`) and asserts the server's +structured output matches field-for-field; a before/after test captures file size+contents, +`git rev-parse HEAD`, and `git status --porcelain` around all five tool calls to prove nothing +writes; a structural test imports the server module in a fresh interpreter and checks +`sys.modules` for absence of `chemenu.commands.*`. + +Added `check_trace_destination()`: the server **refuses to start** if `WIKI_TRACE` is on and +would write into the served checkout's `reports/telemetry/` - the directory the sync's +`git reset --hard` is entitled to wipe. `WIKI_TRACE=0` or `WIKI_TRACE_DIR` outside the corpus +both satisfy it. + +New `instructions/mcp-read-server.md` (agent-facing operating procedure), `tools/requirements-mcp.txt` +(the SDK's dependency, kept out of `requirements.txt` so a CLI-only instance need not install +pydantic/starlette/uvicorn/cryptography), a CI step to install it (so the golden test cannot +silently be skipped), and doc updates (`tools/CONTRACT.md`, `tools/README.md`, `README.md`). + +Bumped `--minor` → **2.4.0**. + +Ran `docs verify`, `instructions verify`, and the full suite (**799 passed**) plus an +empty-machine run (`env -i ... pytest`) with the same result, before presenting the changeset. + +`tools/wikitool publish` hit the **Mass-Update Gate**: 37 files, +3,037/-625 lines, exit 42. +Reproduced the full file-by-area breakdown verbatim in the reply (as the gate's message +requires - the output does not reach the user's screen on its own) and stopped without running +further commands, per the gate's instruction and AGENTS.md invariant 6. + +## Turn 2 - "Freigegeben. Erstelle eine install-MCP.md für Menschen. Für traefik middleware verweise auf https://gitea.nehmer.net/torben/gitea-mcp-forward-auth ... Wir brauchen ein issue, der uns dicker Container für ein deployment erzeugt. Fasse dort schon mal zusammen, was du bisher weißt... Die ci scripte in https://gitea.nehmer.net/torben/gitea-mcp dürfte ein guter startpunkt sein." + +Published with the token from the gate's own printed line +(`--confirm 46442f4419c1`) - commit `576df2c`. + +Fetched both referenced repos via `gitea-mcp` (`get_repository_tree`, `get_file_contents`) to +ground the two follow-up documents in what actually exists rather than in assumption: + +- `gitea-mcp-forward-auth`: a small Go Traefik ForwardAuth service - Bearer-token-vs-SHA-256-hash + checking, `AUTH_PROXY_TOKEN_HASHES_DIR`/`AUTH_PROXY_TOKEN_HASHES` config, `/healthz` always + open, demo token hashes checked into the repo, a registry-image test script with ephemeral + Docker/Podman login. +- `gitea-mcp`: its Dockerfile (multi-stage, `CGO_ENABLED=0`, distroless non-root, OCI labels) is + a usable pattern, but its release workflow pushes to **DockerHub** (`DOCKER_ORG: gitea`) - it + is a fork of the upstream project, so it is *not* a usable registry-push template for this + repo. Noted explicitly rather than silently copied. + +Wrote `install-MCP.md` (later renamed, see Turn 3): six numbered steps (install dependency, run +stdio, wire a client, run streamable-http, put authentication in front, keep the corpus current +via polling), a runnable stdio verification script (executed for real before being written into +the doc, output: `Tools: [...]`, `Seiten: 176 | Commit: `), and a troubleshooting section +keyed to the server's actual error messages. Linked it from `INSTALL.md` and `README.md`, and +added `CHEMENU_ROOT`/`WIKI_TRACE`/`WIKI_TRACE_DIR` to `INSTALL.md`'s configuration table (both +had been in effect since earlier work but undocumented there). Added the file to `dist_cmd.py`'s +`ROOT_FILES` allowlist and verified with a real `dist export` that it ships. + +Filed **issue #37** ("Container-Image für den MCP-Leseserver"): summarized what is already fixed +(startup command, required env vars, the ripgrep-in-the-image trap a naive `pip install` +Dockerfile would miss, where auth/rate-limiting belong) and the concrete templates found above, +then nine explicit open decisions (corpus baked into the image vs. mounted as a volume and +synced by a sidecar; who runs the sync; base image, since Go-style `distroless` does not carry a +Python interpreter or `rg`; how the version reaches the image; whether to build `arm64`; +**a healthcheck endpoint does not exist yet - the one item that implies new code in this repo**; +registry path; OCI labels; whether a smoke test against the built image is added). Labeled +`prio/2 size/M`. + +Closed **#34, #33, #31, #19** with detailed comments each restating what was implemented against +the issue's own acceptance criteria, including the two accidental-dependency findings from #31 +and the corrected alias-bomb numbers. Commented on **#36** with a summary table across all four +versions, noted its closing criterion (a consumer provably reaching the server through the +Traefik middleware) is not yet met - that needs #37's deployment - and proposed leaving #36 open +until then; also carried forward its two remaining loose ends (the wrong `qmd.md` language claim, +and the still-missing place for architecture decisions). + +## Turn 3 - "Freigegeben. Nenne die Datei INSTALL-MCP.md all Caps sonst fahre mit dem Auftrag fort" (interrupting a `dist export` verification call) + +Renamed `install-MCP.md` → `INSTALL-MCP.md`, fixed every reference (`INSTALL.md`, `README.md`, +`tools/chemenu/commands/dist_cmd.py`). Re-ran the full suite (**799 passed**) and `docs verify`, +bumped `--patch` → **2.4.1**, wrote the changelog entry, published (commit `83018fc`). Saved a +feedback memory (`root-docs-are-all-caps.md`): root-level human docs in this repo are named in +ALL CAPS, and a new one has to be added to `dist_cmd.ROOT_FILES` or it silently does not ship. + +## Outcome + +- **Version:** 2.2.2 -> 2.2.3 -> 2.2.4 -> 2.3.0 -> 2.4.0 -> 2.4.1 +- **Commits:** `576df2c` (2.4.0, the 37-file changeset cleared through the Mass-Update Gate), + `83018fc` (2.4.1, `INSTALL-MCP.md` and its wiring) +- **Tests:** 776 -> 786 -> 799 passed, green throughout, including on an `env -i` empty machine +- **Measured:** corpus parse 265ms -> 54ms; `wikitool search` end-to-end 593ms -> 347ms +- **Issues:** #34, #33, #31, #19 closed with detailed comments; #36 commented, left open pending + #37; #37 opened (`prio/2 size/M`) +- **CI:** `.gitea/workflows/ci.yml` updated to install `tools/requirements-mcp.txt`, otherwise + unchanged; not separately re-run in this session (publish triggers it) +- **Not done in this session, carried forward:** #37 itself (container image); #23 (env var + registration enforcement - `CHEMENU_ROOT` was added to `_WIKITOOL_ENV` by hand); the `qmd.md` + language-claim fix (separate transcript); an ADR-style home for architecture decisions