MCP Fusion/Core concepts/Tool-Exposition

Tool-Exposition

Frag die KI über Vinkius

Definieren Sie Aktionen einmal und wählen Sie ihre Darstellung auf der Leitung: ein gruppiertes Tool mit Discriminator oder ein atomares Tool pro Aktion, ergänzt durch Sichtbarkeit per Tags und Aktionsschemas.

Wie Sie einen Connector erstellen und wie der Agent ihn sieht, sind in MCP Fusion zwei verschiedene Entscheidungen. Die Expositionsschicht liegt dazwischen: Sie nimmt Ihre Builder und kompiliert die tools/list-Oberfläche, die der Client erhält. Wechseln Sie die Strategie, ohne einen Handler anzufassen.

Namespaces: ein Tool, viele Aktionen

Beim Erstellen verwenden Sie Namen mit Punkten, wobei der erste Punkt den Namespace von der Aktion trennt:

Sie schreiben	MCP-Tool	Aktion
`f.query('billing.get_invoice')`	`billing`	`get_invoice`
`f.mutation('billing.refund')`	`billing`	`refund`
`f.action('support.tickets.search')`	`support.tickets`	`search`

Tool-Namen enthalten höchstens einen Punkt. Verschachtelte Präfixe verwenden f.router('support.tickets'). Builder mit gemeinsamem Namespace werden vom Registry zusammengeführt. Drei Dateien, die compliance.scan, compliance.report und compliance.status exportieren, erzeugen daher ein compliance-Tool mit drei Aktionen. Der Agent sieht eine zusammenhängende Oberfläche, während Sie die Organisation mit einer Datei pro Aktion beibehalten.

Zwei Strategien

attachToServer(server, { toolExposition }) wählt die Form auf der Leitung:

Gruppiert ist der Standard für Namespaces mit mehreren Aktionen: ein MCP-Tool pro Namespace mit einem Discriminator-Feld, standardmäßig action, das mit .discriminator('operation') umbenannt werden kann. Der Agent wählt die Aktion als Argument, genau wie bei einer ressourcenorientierten API.

Flach bedeutet ein atomares MCP-Tool pro Aktion mit dem Namen billing_get_invoice, wobei das Trennzeichen konfigurierbar ist. Jedes Tool erhält sein eigenes bereinigtes Schema, in dem gemeinsame Felder nur mit denen dieser Aktion zusammengeführt werden, der Discriminator entfernt ist und eigene Annotationen gelten. Verwenden Sie die flache Form, wenn die Tool-Auswahl des Clients schwach ist oder Aktionen kaum etwas gemeinsam haben.

Flache Tools machen auch HATEOAS-Affordances direkt: Ein .suggest('billing.remind') von einer flachen Oberfläche ist ein Tool, das der Client bereits auflistet.

Wahrheit der Annotationen

Semantische Verben setzen MCP-Annotationen, und die Exposition bewahrt sie pro Aktion:

Builder	Annotation
`f.query()`	`readOnlyHint: true`
`f.mutation()`	`destructiveHint: true`
`f.action()`	neutral
`.idempotent()`	`idempotentHint: true`

Im flachen Modus trägt jedes atomare Tool seine eigenen Hinweise. Im gruppierten Modus trägt das Tool das sicherste Aggregat, und Hinweise pro Aktion stehen in den Schema-Beschreibungen der jeweiligen Aktion. Eine destruktive Mutation, die sich als schreibgeschützt ausgibt, ist eine Lüge, auf die Clients reagieren. Deshalb schließt das Framework keine Sicherheit, die Sie nicht deklariert haben.

Parameter-Annotationen übernehmen die Erklärung

Gruppierte Schemas führen gemeinsame und aktionsspezifische Parameter zusammen. Jede Feldbeschreibung erhält eine Pflichtangabe, die aus den Aktionen selbst erzeugt wird:

Annotation	Bedeutung
`(always required)`	von jeder Aktion des Tools benötigt
`Required for: refund, void`	von allen aufgeführten Aktionen benötigt
`Required for: refund. For: get`	von einigen benötigt, bei anderen optional
`For: get, list`	nie erforderlich, aber von diesen Aktionen verwendet

Der Agent muss die Matrix nicht erst aus Fehlern lernen, denn das Schema stellt sie dar. Zusammen mit dem Discriminator-Enum ist ein gruppiertes Tool eine selbsterklärende API.

Sichtbarkeit per Tag

.tags('billing', 'finance') markiert ein Tool, und attachToServer(server, { filter }) entscheidet, was es veröffentlicht:

typescript

attachToServer(server, {
  filter: {
    tags: ['finance'],          // AND: must carry every tag
    anyTag: ['public'],         // OR: at least one
    exclude: ['internal'],      // NOT
  },
});

Tags ermöglichen es einer Codebasis, mehrere Produkte zu bedienen: Die kostenlose Stufe veröffentlicht öffentliche Tools, die Enterprise-Bereitstellung interne Tools und der Handler-Code bleibt identisch. Siehe Multi-Tenant-Connectoren für die Anfrageversion derselben Idee.

Gruppierung als Tokenstrategie

Jeder Tool-Name, jede Beschreibung und jedes Schema kostet in jedem Turn Kontext. Einhundert flache Tools bedeuten einhundert Beschreibungen, die das Modell vor der Planung liest. Zehn Aktionen in einem Tool mit Discriminator-Enum zu gruppieren, tauscht Schema-Größe gegen Prompt-Größe und ist oberhalb von ungefähr zehn Aktionen meist ein großer Gewinn. .toonDescription() komprimiert die Beschreibung weiter, und compactDescription() liefert die Kurzform für die progressive FSM-Offenlegung. Die Wirtschaftlichkeit wird in Token-Ökonomie behandelt.

Nächste Schritte

Token-Ökonomie: weniger Kontext für dieselbe Oberfläche
FSM-State-Gating: Tools entfernen, die der Zustand verbietet
Routing: wo die Builder auf der Festplatte liegen