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 Toolkatalog wird nicht von Hand gepflegt, sondern aus tools/list des freigegebenen Produktbuilds erzeugt; er folgt, sobald dieser Build benannt ist.

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

#

• Verhandelt wird ausschließlich der Protokollstand 2025-06-18; ältere Stände werden abgelehnt.
• 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 Portfolio sind mutierende Werkzeuge abgelehnt, die Zeitskala ausgenommen.

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.

Was hier noch kommt

#

Nach dem Vertrags-Freeze gegen den freigegebenen Produktbuild: der aus tools/list erzeugte Katalog je Werkzeug mit Zweck, Zugriffsklasse, Parametern, Antwortschema, Lizenz- und Undo-Hinweis und belegtem Beispiel; Seiten zu Authentifizierung, Sicherheit, Fehlersuche und Änderungen je Produktversion. Bis dahin gilt: Was tools/list Ihrer Installation liefert, ist der Vertrag.

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.