Entwickler: der Vertrag des MCP-Servers

Diese Seite beschreibt den Vertrag, den der MCP-Server von Rillsoft Project gegenüber jedem Client einhält: wie ein Werkzeug beschrieben ist, wie Ein- und Ausgabe aufgebaut sind, was ein Fehler enthält und welche Regeln für Undo, Nur-Lesen und Sitzung gelten. Serverstart, Handshake und Zugriffsschutz stehen auf der MCP-Seite. Der vollständige Werkzeugkatalog wird nicht von Hand gepflegt, sondern aus tools/list des genannten Produktbuilds erzeugt.

Was ein Eintrag in tools/list trägt

#

destructiveHint steht konservativ auf true, wo gelöscht, überschrieben, verworfen oder verlustbehaftet gelöst wird. idempotentHint steht nur auf true, wenn derselbe Aufruf fachlich wiederholbar dieselbe Wirkung hat. openWorldHint ist true bei Datei- und Netzzugriffen, false bei reinem Zugriff auf das Dokumentmodell. Die Liste ist ordinal nach Namen sortiert, damit ein Client seinen Cache behält; die Reihenfolge ist Sortierung, kein Vertrag über Positionen.

Beide Schemata werden zur Laufzeit durchgesetzt. Argumente prüft der Server, bevor der Aufruf die Anwendung erreicht; ein strukturell ungültiger Aufruf berührt das Projekt nie und hinterlässt keinen Undo-Schritt. Jedes erfolgreiche structuredContent wird gegen sein outputSchema geprüft; ein Verstoß ist ein interner Fehler, keine stille Auslieferung.

Sprachgrenze

#

Der Server hat keine Sitzungssprache. Er antwortet jedem Client in der Sprache des laufenden Rillsoft Project – deutsch, englisch oder russisch. Was maschinell gelesen wird, bleibt dabei überall gleich:

Auch eine lokalisierte Meldung nennt taskUuid, machine_role oder rillsoft_resource_pool_catalog_list unverändert – der Leser soll daraus den nächsten Aufruf bauen können.

Feldnamen und Wertebereiche

#

• Argumente und Ergebnisfelder tragen englische lowerCamelCase-Namen, und derselbe fachliche Wert heißt in beiden Richtungen gleich: Was der Projektbaum als durationHours liefert, nimmt die Vorgangsänderung als durationHours an. Eine Antwort lässt sich ohne Umbenennen weiterreichen.
• Enumwerte sind englisches lower_snake_case: machine_role, capacity_driven, resource_chart; einteilige Werte bleiben ein Wort. Die fünf Verknüpfungstypen heißen finish_start, finish_start_no_delay, start_start, finish_finish und start_finish.
• Jeder abgegrenzte Wertebereich steht als enum im inputSchema; die description erklärt die Bedeutung der Werte und zieht die Grenze zum Nachbarwert.
• Zeitangaben im Format DD.MM.YYYY hh:mm (Uhrzeit optional) oder YYYY-MM-DDThh:mm; Dauern in Stunden. Ein Datum wie 31.02.2026 wird abgelehnt statt still auf den 3. März gerundet.
• Objekte werden über ihre UUID adressiert; jeder erzeugende Aufruf gibt sie zurück. WBS-Codes vergibt Rillsoft Project selbst.
• Lesbare Beschriftungen aus der Oberfläche heißen label; sie hängen an der Sprache und sind keine Schlüssel.

Antwort und Fehler

#

Jede Werkzeugantwort liefert das Ergebnis doppelt: als Klartext in content[0].text (JSON, bei Reports YAML) und maschinenlesbar in structuredContent. Eine fachliche Ablehnung kommt als isError: true mit dem stabilen Code in _meta.errorCode; die erste Zeile des Textes wiederholt den Code:

{"id":9,"jsonrpc":"2.0","result":{"content":[{"text":"errorCode: rejected\nKein Vorgang mit UUID 'xyz' gefunden","type":"text"}],"isError":true,"_meta":{"errorCode":"rejected"}}}

Derselbe Fehler in drei Builds – der Code ist die Kennung, der Text die Erklärung:

Schemaverstöße kommen als JSON-RPC-Fehler -32602 mit error.data.code und einem sprachneutralen Feldpfad in error.data.field, etwa arguments.criterion mit der Liste der erlaubten Werte. Die Fehlerklassen:

Der Vorrat an Codes ist auf Kategorieebene geschnitten – rund dreißig Codes statt dreihundert Meldungen. Eine Ablehnung ohne Code gibt es nicht; wo ein Handler keinen setzt, steht der Sammelcode rejected. Wiederholungsregeln baut man auf den Code, nie auf den Wortlaut.

Zugriffsklassen, Undo und Sitzung

#

Jedes Werkzeug gehört zu genau einer Zugriffsklasse. Aus ihr entstehen der readOnlyHint und die Filterung im Nur-Lesen-Modus, damit beide nicht auseinanderlaufen können.

Undo und Redo sind selbst Werkzeuge und bedienen dieselbe Historie wie die Oberfläche, auch für Schritte, die ein Mensch dort gemacht hat. Die Historie legt je Kommando einen vollständigen Schnappschuss an; sehr viele Einzelaufrufe kosten deshalb Zeit.

Protokollregeln, die abweichen können

#

• Der Server arbeitet mit Protokollstand 2025-06-18. Fragt ein Client in initialize einen anderen Stand an, antwortet der Server seit Build 10.0.625 mit 2025-06-18; der Client entscheidet, ob er damit weiterarbeitet.
• initialize vergibt Mcp-Session-Id; notifications/initialized schaltet die Werkzeuge frei. Jede weitere Anfrage trägt Sitzung und MCP-Protocol-Version, sonst 400. Höchstens 32 Sitzungen, Verfall nach 30 Minuten Leerlauf, DELETE /mcp beendet.
• JSON-RPC-Batches werden abgelehnt. Nur das Fehlen von id kennzeichnet eine Notification; id: null ist ein Request.
• params.arguments ist Pflicht, sobald das Werkzeug Parameter hat; ein vergessenes arguments wäre sonst ein stiller Aufruf mit Standardwerten.
• Pfade sind absolut (Laufwerk oder UNC) mit passender Endung; Listen oder Löschen von Dateien gibt es bewusst nicht.
• Portfolios haben ein eigenes Öffnen-Werkzeug; das Projekt-Werkzeug lehnt eine .rpp mit Verweis ab und umgekehrt. Im geöffneten Portfolio arbeiten die Werkzeuge wie im einzelnen Projekt – mit den Grenzen der Oberfläche: nichts direkt unter dem Portfolio, kein Element und im Datei-Portfolio keine Abhängigkeit über die Projektgrenze, kein Basisplan, kein Speichern unter.

Ein Durchstich in achtzehn Aufrufen

#

Der dokumentierte End-to-End-Ablauf über alle Bereiche, mit der mcp-Funktion von der MCP-Seite; <A> ist die UUID aus dem Ergebnis des erzeugenden Aufrufs:

# Aufbau und Zuweisung
mcp '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"rillsoft_project_create","arguments":{"name":"Demo","discardChanges":true}}}'
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rillsoft_project_update","arguments":{"start":"05.10.2026 08:00","finish":"27.11.2026 17:00","fixed":true}}}'
mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rillsoft_task_create","arguments":{"name":"Vorgang A","start":"05.10.2026 08:00","durationHours":16}}}'
mcp '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"rillsoft_task_role_assignment_set","arguments":{"taskUuid":"<A>","roleId":11001,"quantity":2}}}'

# Basisplan sichern, dann den Plan ändern
mcp '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"rillsoft_baseline_create","arguments":{"name":"Plan V1"}}}'
mcp '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"rillsoft_task_update","arguments":{"uuid":"<A>","durationHours":24}}}'

# Ist-Daten erfassen
mcp '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"rillsoft_task_progress_set","arguments":{"uuid":"<A>","progressPercent":50}}}'
mcp '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"rillsoft_project_status_date_set","arguments":{"statusDate":"07.10.2026 08:00"}}}'

# Soll/Ist-Auswertung (Zeit) …
mcp '{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"rillsoft_view_state_apply","arguments":{"view":{"name":"time_variance"}}}}'
mcp '{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"rillsoft_variance_report_get","arguments":{}}}'
# → Soll 16 h, Ist 24 h, Abweichung 8 h

# … und Ressourcenauslastung, verdichtet auf Wochen
mcp '{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"rillsoft_view_state_apply","arguments":{"view":{"name":"employee_capacity"}}}}'
mcp '{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"rillsoft_timescale_apply","arguments":{"unit":"week"}}}'
mcp '{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"rillsoft_analysis_report_get","arguments":{}}}'

# Speichern, Fehlgriff zurücknehmen, gespeicherten Stand wieder öffnen
mcp '{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"rillsoft_project_file_save_as","arguments":{"path":"C:/Projekte/Demo.rpj"}}}'
mcp '{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"rillsoft_task_update","arguments":{"uuid":"<A>","durationHours":40}}}'
mcp '{"jsonrpc":"2.0","id":16,"method":"tools/call","params":{"name":"rillsoft_history_undo","arguments":{}}}'
mcp '{"jsonrpc":"2.0","id":17,"method":"tools/call","params":{"name":"rillsoft_project_file_save","arguments":{}}}'
mcp '{"jsonrpc":"2.0","id":18,"method":"tools/call","params":{"name":"rillsoft_project_file_open","arguments":{"path":"C:/Projekte/Demo.rpj","discardChanges":true}}}'

Jeder mutierende Schritt ist im sichtbaren Rillsoft Project live nachvollziehbar und dort einzeln mit Strg+Z rücknehmbar; die Dateischritte erzeugen keinen Undo-Schritt. Nach jedem mutierenden Aufruf liegt der neu berechnete Plan vor – Termine, Puffer, kritischer Pfad –, nicht nur der geänderte Datensatz; die Auswertungen in Schritt 10 und 13 lesen genau diesen Stand. Die Dokumentation schließt den Durchstich mit einem 19. lesenden Aufruf (rillsoft_project_tree_get), der den gespeicherten Stand kontrolliert. Die Rollen-Id im Beispiel stammt aus dem Referenzpool der Dokumentation – in Ihrem Pool liefert sie der Katalogaufruf.

Repository und Verzeichnisse

#

Die Einrichtung für KI-Clients liegt zusätzlich als öffentliches Repository auf GitHub: Dokumentation und Client-Konfiguration des MCP-Servers auf GitHub – README auf Deutsch und Englisch, Konfigurationsbeispiele mit und ohne API-Key. Das Repository enthält inzwischen auch einen Launcher als Brücke zum lokalen Endpunkt. Der eigentliche Server ist Teil von Rillsoft Project 10 und wird dort eingeschaltet.

In der offiziellen MCP-Registry steht der Server unter dem Namen ai.rillsoft/rillsoft-project, nachgewiesen über die Domain rillsoft.ai. Verzeichnisse, die aus der Registry lesen, übernehmen den Eintrag von dort.

Anleitungen und Referenzen

#

Die vollständigen Abläufe finden Sie in der Claude-Anleitung, den Beispielen zum Erstellen und Ändern von Projekten und zur Kapazitätsprüfung sowie der Referenz für Fehler, Undo und sichere Schreibzugriffe.

Der Werkzeugkatalog führt bereits jedes Werkzeug mit Titel, Zugriffsart, Parametern und Beschreibung, erzeugt aus tools/list von Build 10.0.626. Noch folgen: je Werkzeug das Antwortschema in Worten, Lizenz- und Undo-Hinweis und ein belegtes Beispiel sowie Änderungen je Produktversion. Maßgeblich bleibt, was tools/list Ihrer Installation liefert.

Produktversion

Rillsoft Project 10

Belegstatus

Angaben aus der Produktdokumentation von Rillsoft Project 10 (Stand 08.09.2026); der Abgleich mit dem freigegebenen Build steht aus.