@appport/mcp 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @appport/mcp
+
+Expose AppPort capabilities as MCP tools.
+
+```ts
+import { createMcpBridge } from "@appport/mcp";
+
+const bridge = createMcpBridge(application, { session });
+
+bridge.listTools();
+await bridge.callTool("documents_save", { documentId, content });
+```
+
+The layering matters:
+
+```
+AI -> MCP -> AppPort -> application
+```
+
+AppPort does not compete with MCP; it is the application protocol underneath it.
+A capability that is already defined, validated, versioned and authorized becomes
+an agent tool without a second definition, and the agent's session decides what
+it may call. A tool call runs the same dispatch pipeline as any other request, so
+`INVALID_INPUT` and `FORBIDDEN` reach the agent as tool errors rather than as
+unexpected behaviour.
+
+Tool names map to capability names (`documents.save` becomes `documents_save`)
+and the tool's input schema is the capability's published JSON Schema. Stream
+capabilities and the reserved `appport.*` namespace are excluded by default.

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `@appport/mcp` — expose AppPort capabilities as MCP tools (§65).
+ *
+ * The layering matters: AI → MCP → AppPort → application. AppPort does not
+ * compete with MCP; it is the application protocol underneath it, so a
+ * capability that is already defined, validated and authorized becomes an agent
+ * tool without a second definition.
+ */
+import { type AppPortManifest, type CapabilityManifestEntry, type JSONSchema } from "@appport/protocol";
+import type { AppPortApplication, DispatchOptions } from "@appport/core";
+/** The subset of the MCP tool descriptor AppPort can fill in from a manifest. */
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    /** Non-standard annotation naming the capability this tool came from. */
+    _appport: {
+        capability: string;
+        version: number;
+        authorization: string[];
+        outputSchema: JSONSchema;
+    };
+}
+export interface McpContent {
+    type: "text";
+    text: string;
+}
+export interface McpToolResult {
+    content: McpContent[];
+    isError?: boolean;
+}
+export interface McpBridgeOptions {
+    /** Capability names to expose. Defaults to every request capability. */
+    include?: (entry: CapabilityManifestEntry) => boolean;
+    /** Prefix applied to generated tool names, e.g. `docs`. */
+    prefix?: string;
+    /** Expose the reserved `appport.*` capabilities. Defaults to false. */
+    includeBuiltins?: boolean;
+}
+/** MCP tool names are conventionally `[a-z0-9_-]`; capability names are dotted. */
+export declare function toToolName(capability: string, prefix?: string): string;
+export declare function fromToolName(tool: string, prefix?: string): string;
+/** Renders the manifest's request capabilities as MCP tool descriptors. */
+export declare function toMcpTools(manifest: AppPortManifest, options?: McpBridgeOptions): McpTool[];
+/**
+ * A minimal MCP server surface over an AppPort application.
+ *
+ * Wire `listTools` and `callTool` into an MCP server implementation; the
+ * dispatch pipeline — validation, authorization, telemetry — is unchanged, so
+ * an agent has exactly the access its session grants and no more.
+ */
+export interface McpBridge {
+    listTools(): McpTool[];
+    callTool(name: string, args: unknown): Promise<McpToolResult>;
+}
+export declare function createMcpBridge(application: AppPortApplication, dispatch?: DispatchOptions, options?: McpBridgeOptions): McpBridge;
+/** Turns an AppPort error into the text an agent should see. */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzE,iFAAiF;AACjF,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,UAAU,CAAA;KAAE,CAAC;CACtG;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC;IACtD,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,EAAE,CAmB/F;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,IAAI,OAAO,EAAE,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/D;AAED,wBAAgB,eAAe,CAC7B,WAAW,EAAE,kBAAkB,EAC/B,QAAQ,GAAE,eAAoB,EAC9B,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAiCX;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/index.js

@@ -0,0 +1,70 @@
+/**
+ * `@appport/mcp` — expose AppPort capabilities as MCP tools (§65).
+ *
+ * The layering matters: AI → MCP → AppPort → application. AppPort does not
+ * compete with MCP; it is the application protocol underneath it, so a
+ * capability that is already defined, validated and authorized becomes an agent
+ * tool without a second definition.
+ */
+import { AppPortError, createRequest, newRequestId } from "@appport/protocol";
+/** MCP tool names are conventionally `[a-z0-9_-]`; capability names are dotted. */
+export function toToolName(capability, prefix) {
+    const base = capability.replace(/\./g, "_");
+    return (prefix ? `${prefix}_${base}` : base).slice(0, 64);
+}
+export function fromToolName(tool, prefix) {
+    const withoutPrefix = prefix && tool.startsWith(`${prefix}_`) ? tool.slice(prefix.length + 1) : tool;
+    return withoutPrefix.replace(/_/g, ".");
+}
+/** Renders the manifest's request capabilities as MCP tool descriptors. */
+export function toMcpTools(manifest, options = {}) {
+    const includeBuiltins = options.includeBuiltins ?? false;
+    return manifest.capabilities
+        .filter((entry) => entry.kind === "request")
+        .filter((entry) => includeBuiltins || !entry.name.startsWith("appport."))
+        .filter((entry) => options.include?.(entry) ?? true)
+        .map((entry) => ({
+        name: toToolName(entry.name, options.prefix),
+        description: entry.description ??
+            `Invokes the ${entry.name} capability of ${manifest.application.name} (version ${entry.latestVersion}).`,
+        inputSchema: entry.inputSchema,
+        _appport: {
+            capability: entry.name,
+            version: entry.latestVersion,
+            authorization: entry.authorization,
+            outputSchema: entry.outputSchema
+        }
+    }));
+}
+export function createMcpBridge(application, dispatch = {}, options = {}) {
+    const tools = () => toMcpTools(application.manifest(), options);
+    return {
+        listTools: tools,
+        async callTool(name, args) {
+            const tool = tools().find((entry) => entry.name === name);
+            if (!tool) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }]
+                };
+            }
+            const response = await application.handleRequest(createRequest({
+                requestId: newRequestId(),
+                capability: { name: tool._appport.capability, version: tool._appport.version },
+                input: args ?? {}
+            }), { transport: "mcp", ...dispatch });
+            if (!response.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `${response.error.code}: ${response.error.message}` }]
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(response.output, null, 2) }] };
+        }
+    };
+}
+/** Turns an AppPort error into the text an agent should see. */
+export function describeError(error) {
+    return AppPortError.is(error) ? `${error.code}: ${error.message}` : "INTERNAL_ERROR: the capability failed";
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@appport/mcp",
+  "version": "1.0.0",
+  "description": "Expose AppPort capabilities as MCP tools.",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/rkendel1/appport.git", "directory": "packages/mcp" },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean"
+  },
+  "dependencies": {
+    "@appport/protocol": "1.0.0",
+    "@appport/core": "1.0.1"
+  },
+  "publishConfig": { "access": "public" }
+}