@agdf/mcp-server 0.20.1 → 0.20.2

package/README.md

@@ -1,11 +1,12 @@
 # @agdf/mcp-server
 
-Local STDIO MCP adapter for AGDF dispatch and control inspection.
+Local STDIO MCP adapter.
 
 MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
 
-The bounded write groups, selected contract/status reads, original-operation recovery and
-focused app-only decision facade are described in [Core and MCP command flow](../../docs/architecture/core-mcp-command-flow.md).
+[Integration guide](../../docs/architecture/09-mcp-integrationsrichtlinien.md).
+[Command flow](../../docs/architecture/core-mcp-command-flow.md): bounded writes,
+contract/status reads, original-operation recovery and the app-only decision facade.
 Host tool permission is separate from a deliberate gate decision. The source candidate's
 click actions remain disabled while native app-only mediation is unqualified.
 
@@ -53,8 +54,7 @@ service itself remains read-only. Accordingly, `agdf_dispatch` declares `readOnl
 
 > [!IMPORTANT]
 > This package documents the repository development build. The previously published AGDF 0.14.5 release
-> did not include the MCP support described here. Repository assemblies and local plugin builds still
-> carry the canonical version `0.14.5`, but can contain these newer MCP features. The version alone
+> did not include the MCP support described here. Current assemblies and local plugin builds take their version from the canonical package manifests. The version alone
 > does not identify the payload: verify the assembly or installed runtime digests and the loaded session.
 > These development instructions do not establish what a current npm `@latest` resolution contains.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agdf/mcp-server",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Local MCP adapter for version-matched AGDF dispatch and control inspection.",
   "type": "module",
   "files": [
@@ -19,7 +19,7 @@
   "scripts": {},
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "create-agdf": "0.20.1"
+    "create-agdf": "0.20.2"
   },
   "engines": {
     "node": ">=22"

package/src/server.js

@@ -5,7 +5,8 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { DispatchExecutionError, createWorkerDispatchExecutor } from "./worker.js";
 import { loadCockpitResource } from './cockpit-resource.js';
-import { requestDeclaresMcpAppUi, requestMcpClientInfo, requestMcpClientCapabilities } from "./ui-capability.js";
+import { requestDeclaresMcpAppUi, requestMcpClientInfo, requestMcpClientCapabilities, requiresMcpAppUi,
+  missingMcpAppUi, capabilityTransport, modernToolUiDenial } from "./ui-capability.js";
 
 export const SERVER_NAME = "agdf-mcp";
 
@@ -38,7 +39,7 @@ function toolResult(runtime, name, input, result, serialize = runtime.serialize,
   return response;
 }
 
-export function buildAgdfServer({ runtime, executor } = {}) {
+export function buildAgdfServer({ runtime, executor, era } = {}) {
   if (!runtime?.definition || typeof runtime.serialize !== "function") {
     throw new TypeError("AGDF MCP runtime is required");
   }
@@ -57,7 +58,14 @@ export function buildAgdfServer({ runtime, executor } = {}) {
     },
     close: async () => runtime.close?.(),
   };
-  const server = new McpServer(
+  const registrations = new Map();
+  class AgdfServer extends McpServer {
+    async connect(transport) {
+      return super.connect(capabilityTransport(transport, message => modernToolUiDenial(message,
+        { era: era ?? (this.server.getNegotiatedProtocolVersion() === '2026-07-28' ? 'modern' : 'legacy'), runtime, registrations })));
+    }
+  }
+  const server = new AgdfServer(
     { name: SERVER_NAME, version: runtime.trustedContext.expectedVersion },
     { capabilities: { tools: {}, ...(runtime.ui ? { resources: {} } : {}) } },
   );
@@ -87,12 +95,13 @@ export function buildAgdfServer({ runtime, executor } = {}) {
   } };
   for (const tool of tools) {
     const { name, definition, serialize } = tool;
-    server.registerTool(
+    const schema = fromJsonSchema(definition.inputSchema, deferredSchemas);
+    const registered = server.registerTool(
       name,
       {
         description: definition.description,
         annotations: definition.annotations,
-        inputSchema: fromJsonSchema(definition.inputSchema, deferredSchemas),
+        inputSchema: schema,
         ...(definition.outputSchema ? { outputSchema: fromJsonSchema(definition.outputSchema, deferredSchemas) } : {}),
         ...(definition._meta ? { _meta: definition._meta } : {}),
       },
@@ -125,12 +134,16 @@ export function buildAgdfServer({ runtime, executor } = {}) {
         }
       },
     );
+    registrations.set(name, { tool, schema, registered });
   }
   if (runtime.ui) {
     const resource = loadCockpitResource(runtime.ui);
     server.registerResource(runtime.mode === 'decision' ? 'AGDF Gate Decision' : runtime.ui.label ?? 'AGDF Cockpit', resource.uri, { mimeType: resource.mimeType, _meta: resource._meta },
       async (_uri, context) => {
-        if (!uiAllowed(context) || runtime.mode === 'decision' && !supportsUi(context)) throw new ProtocolError(ProtocolErrorCode.InvalidParams, "resource_denied");
+        if (requiresMcpAppUi(runtime, { requiresUi: runtime.mode === 'decision' }) && !supportsUi(context)) {
+          if ((era ?? (server.server.getNegotiatedProtocolVersion() === '2026-07-28' ? 'modern' : 'legacy')) === 'modern') throw missingMcpAppUi(runtime.ui.mimeType);
+          throw new ProtocolError(ProtocolErrorCode.InvalidParams, "resource_denied");
+        }
         return { contents: [resource] };
       });
     if (gated || runtime.mode === 'decision') {
@@ -155,8 +168,8 @@ export function buildAgdfServer({ runtime, executor } = {}) {
 
 export function serveAgdfStdio({ runtime, executor, onerror } = {}) {
   const instances = new Set();
-  const handle = serveStdio(() => {
-    const server = buildAgdfServer({ runtime, executor });
+  const handle = serveStdio(({ era }) => {
+    const server = buildAgdfServer({ runtime, executor, era });
     instances.add(server);
     return server;
   }, {

package/src/ui-capability.js

@@ -1,7 +1,55 @@
-import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, MissingRequiredClientCapabilityError, classifyInboundRequest } from "@modelcontextprotocol/server";
 
 // Extension id under which MCP Apps hosts declare UI support (@modelcontextprotocol/ext-apps EXTENSION_ID).
 export const MCP_APP_UI_EXTENSION = "io.modelcontextprotocol/ui";
+export const requiresMcpAppUi = (runtime, tool) => runtime.mode === 'cockpit' && runtime.uiCapabilityRequired === true || tool?.requiresUi === true;
+export const missingMcpAppUi = mimeType => new MissingRequiredClientCapabilityError({
+  requiredCapabilities: { extensions: { [MCP_APP_UI_EXTENSION]: { mimeTypes: [mimeType] } } },
+}, 'resource_denied');
+
+// One narrow Transport decorator; framing, request dispatch, validation and
+// pending-id/drain accounting remain with the original SDK connection.
+export function capabilityTransport(transport, denial) {
+  const wrapped = {
+    onmessage: transport.onmessage,
+    onerror: transport.onerror,
+    onclose: transport.onclose,
+    start: () => transport.start(),
+    send: (message, options) => transport.send(message, options),
+    close: () => transport.close(),
+    get sessionId() { return transport.sessionId; },
+    set sessionId(value) { transport.sessionId = value; },
+    get hasPerRequestStream() { return transport.hasPerRequestStream; },
+  };
+  for (const method of ['setProtocolVersion', 'setSupportedProtocolVersions']) {
+    if (transport[method]) wrapped[method] = (...args) => transport[method](...args);
+  }
+  transport.onerror = error => wrapped.onerror?.(error);
+  transport.onclose = () => wrapped.onclose?.();
+  transport.onmessage = (message, extra) => {
+    const error = denial(message);
+    if (!error) { wrapped.onmessage?.(message, extra); return; }
+    // Sending through the original channel settles its pending request id.
+    Promise.resolve().then(() => transport.send({ jsonrpc: '2.0', id: message.id,
+      error: { code: error.code, message: error.message, data: error.data } }))
+      .catch(cause => wrapped.onerror?.(cause));
+  };
+  return wrapped;
+}
+
+export function modernToolUiDenial(message, { era, runtime, registrations }) {
+  if (era !== 'modern' || message?.method !== 'tools/call') return null;
+  const classified = classifyInboundRequest({ httpMethod: 'POST', body: message });
+  if (classified.kind !== 'modern' || classified.messageKind !== 'request') return null;
+  const entry = registrations.get(message.params?.name);
+  if (!entry?.registered.enabled || !requiresMcpAppUi(runtime, entry.tool)
+      || declaresMcpAppUi(message.params?._meta?.[CLIENT_CAPABILITIES_META_KEY], runtime.ui.mimeType)) return null;
+  const checked = entry.schema['~standard'].validate(message.params.arguments ?? {});
+  // The pinned fromJsonSchema provider is synchronous. Never treat an unknown
+  // asynchronous provider as proof that arguments passed validation.
+  if (checked?.then || checked.issues?.length) return null;
+  return missingMcpAppUi(runtime.ui.mimeType);
+}
 export const requestMcpClientInfo = (server, context) => context?.mcpReq?.envelope?.[CLIENT_INFO_META_KEY] ?? server.getClientVersion();
 export const requestMcpClientCapabilities = (server, context) => context?.mcpReq?.envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.getClientCapabilities();