@capixjs/transport-mcp 0.1.0-alpha.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capix Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * index.ts — public API for capix-transport-mcp
+ */
+export { mcpTransport } from './transport.js';
+export type { McpTransportOptions } from './transport.js';
+export { buildMcpServer, buildTools, toToolName } from './server-builder.js';
+export type { McpServerOptions } from './server-builder.js';
+//# 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;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * index.ts — public API for capix-transport-mcp
+ */
+export { mcpTransport } from './transport.js';
+export { buildMcpServer, buildTools, toToolName } from './server-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/server-builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * server-builder.ts — converts a Capix registry into an MCP server.
+ *
+ * Every capability becomes an MCP tool:
+ *   - Dot-path names become underscore-separated tool names (users.getUser → users_getUser)
+ *   - Zod input schema → tool inputSchema (JSON Schema, input side)
+ *   - Zod object output schema → tool outputSchema + structuredContent
+ *   - intent → tool annotations (query → readOnlyHint, delete → destructiveHint)
+ *
+ * Requests run through the execution engine's invoke() — guards, input
+ * validation, and typed errors behave exactly as on every other transport.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { CapabilityRegistry, InvokeFn } from '@capixjs/core';
+export type McpServerOptions = {
+    /** Server name reported during the MCP handshake. Default: 'capix'. */
+    readonly name?: string;
+    /** Server version reported during the MCP handshake. Default: '0.0.0'. */
+    readonly version?: string;
+    /** Per-call timeout in milliseconds. Default: 30 000. */
+    readonly timeoutMs?: number;
+};
+/** users.getUser → users_getUser (MCP tool names allow [a-zA-Z0-9_-] only). */
+export declare function toToolName(dotPath: string): string;
+/** Builds the tools/list payload from a compiled registry. */
+export declare function buildTools(registry: CapabilityRegistry): {
+    tools: Tool[];
+    byName: Map<string, string>;
+};
+/**
+ * Builds an MCP Server serving every capability in the registry as a tool.
+ * One Server instance per MCP connection — call this once per stdio session
+ * or per stateless HTTP request.
+ */
+export declare function buildMcpServer(registry: CapabilityRegistry, invoke: InvokeFn, options?: McpServerOptions): Server;
+//# sourceMappingURL=server-builder.d.ts.map

package/dist/server-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-builder.d.ts","sourceRoot":"","sources":["../src/server-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAkB,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAG/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAiBD,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA2CvG;AAcD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,QAAQ,EAChB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAgDR"}

package/dist/server-builder.js

@@ -0,0 +1,126 @@
+/**
+ * server-builder.ts — converts a Capix registry into an MCP server.
+ *
+ * Every capability becomes an MCP tool:
+ *   - Dot-path names become underscore-separated tool names (users.getUser → users_getUser)
+ *   - Zod input schema → tool inputSchema (JSON Schema, input side)
+ *   - Zod object output schema → tool outputSchema + structuredContent
+ *   - intent → tool annotations (query → readOnlyHint, delete → destructiveHint)
+ *
+ * Requests run through the execution engine's invoke() — guards, input
+ * validation, and typed errors behave exactly as on every other transport.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { inferIntent } from '@capixjs/core';
+const EMPTY_INPUT_SCHEMA = { type: 'object', properties: {} };
+/** users.getUser → users_getUser (MCP tool names allow [a-zA-Z0-9_-] only). */
+export function toToolName(dotPath) {
+    return dotPath.replaceAll('.', '_');
+}
+/** Converts a Zod schema to JSON Schema; null when conversion fails. */
+function toJsonSchema(schema, io) {
+    try {
+        const js = z.toJSONSchema(schema, {
+            io,
+            reused: 'inline',
+            unrepresentable: 'any',
+        });
+        delete js['$schema'];
+        return js;
+    }
+    catch {
+        return null;
+    }
+}
+/** Builds the tools/list payload from a compiled registry. */
+export function buildTools(registry) {
+    const tools = [];
+    const byName = new Map();
+    for (const [dotPath, cap] of registry) {
+        const name = toToolName(dotPath);
+        byName.set(name, dotPath);
+        // Same rule as the REST router: explicit intent wins, otherwise infer
+        // from the capability's key name (getUser → query, deleteUser → delete).
+        const key = dotPath.split('.').pop() ?? dotPath;
+        const intent = cap._intentExplicit ? cap.intent : inferIntent(key);
+        const inputJs = cap.inputSchema !== null ? toJsonSchema(cap.inputSchema, 'input') : null;
+        // MCP requires inputSchema to be an object schema. Non-object inputs
+        // (z.record works; z.string() does not decompose) fall back to a
+        // permissive object — the engine still validates the real schema.
+        const inputSchema = inputJs !== null && inputJs['type'] === 'object'
+            ? inputJs
+            : EMPTY_INPUT_SCHEMA;
+        const outputJs = cap.outputSchema !== null ? toJsonSchema(cap.outputSchema, 'output') : null;
+        const outputSchema = outputJs !== null && outputJs['type'] === 'object'
+            ? outputJs
+            : undefined;
+        tools.push({
+            name,
+            description: `Capix capability '${dotPath}' (intent: ${intent})`,
+            inputSchema,
+            ...(outputSchema !== undefined ? { outputSchema } : {}),
+            annotations: {
+                title: dotPath,
+                readOnlyHint: intent === 'query',
+                destructiveHint: intent === 'delete',
+                idempotentHint: intent === 'query' || intent === 'replace' || intent === 'delete',
+            },
+        });
+    }
+    return { tools, byName };
+}
+function errorResult(error) {
+    const issues = Array.isArray(error.meta?.['issues']) ? error.meta['issues'] : null;
+    const text = `${error.error}: ${error.message}` +
+        (issues !== null ? `\n${issues.map((i) => `- ${String(i)}`).join('\n')}` : '');
+    return { content: [{ type: 'text', text }], isError: true };
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Builds an MCP Server serving every capability in the registry as a tool.
+ * One Server instance per MCP connection — call this once per stdio session
+ * or per stateless HTTP request.
+ */
+export function buildMcpServer(registry, invoke, options = {}) {
+    const { tools, byName } = buildTools(registry);
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const server = new Server({ name: options.name ?? 'capix', version: options.version ?? '0.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const dotPath = byName.get(request.params.name);
+        if (dotPath === undefined) {
+            return {
+                content: [{ type: 'text', text: `NotFound: unknown tool '${request.params.name}'` }],
+                isError: true,
+            };
+        }
+        // Headers reach context builders on HTTP connections; stdio has none.
+        const rawHeaders = extra.requestInfo?.headers ?? {};
+        const headers = {};
+        for (const [key, val] of Object.entries(rawHeaders)) {
+            if (val !== undefined)
+                headers[key] = Array.isArray(val) ? val.join(', ') : val;
+        }
+        const signal = typeof AbortSignal.any === 'function'
+            ? AbortSignal.any([extra.signal, AbortSignal.timeout(timeoutMs)])
+            : AbortSignal.timeout(timeoutMs);
+        const response = await invoke({
+            capability: dotPath,
+            input: request.params.arguments ?? {},
+            headers,
+            signal,
+        });
+        if (!response.ok)
+            return errorResult(response.error);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response.data) }],
+            ...(isPlainObject(response.data) ? { structuredContent: response.data } : {}),
+        };
+    });
+    return server;
+}
+//# sourceMappingURL=server-builder.js.map

package/dist/server-builder.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * transport.ts — MCP transport for Capix.
+ *
+ * Two modes:
+ *   - stdio: the process becomes an MCP server over stdin/stdout. For local
+ *     use with MCP clients (Claude Code, editors). Diagnostics go to stderr —
+ *     stdout belongs to the protocol.
+ *   - http: serves the MCP Streamable HTTP transport (stateless) on a port,
+ *     mountable alongside the other Capix transports. Request headers are
+ *     forwarded to the context builder like on the REST transport.
+ *
+ * Mode is inferred: pass `port` for http, omit it for stdio.
+ */
+import type { GroupTree, TransportWithCapabilities } from '@capixjs/core';
+import type { McpServerOptions } from './server-builder.js';
+export type McpTransportOptions = McpServerOptions & {
+    /** Listen port. When set, serves Streamable HTTP; when omitted, serves stdio. */
+    readonly port?: number;
+    readonly host?: string;
+    /** URL path for the MCP endpoint in http mode. Default: '/mcp'. */
+    readonly path?: string;
+    /** Capability registry for this transport only. Overrides the server-level default. */
+    readonly capabilities?: GroupTree;
+};
+export declare function mcpTransport(options?: McpTransportOptions): TransportWithCapabilities;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAqC,SAAS,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAE7G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAS5D,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG;IACnD,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC;CACnC,CAAC;AAEF,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,yBAAyB,CAmFzF"}

package/dist/transport.js

@@ -0,0 +1,95 @@
+/**
+ * transport.ts — MCP transport for Capix.
+ *
+ * Two modes:
+ *   - stdio: the process becomes an MCP server over stdin/stdout. For local
+ *     use with MCP clients (Claude Code, editors). Diagnostics go to stderr —
+ *     stdout belongs to the protocol.
+ *   - http: serves the MCP Streamable HTTP transport (stateless) on a port,
+ *     mountable alongside the other Capix transports. Request headers are
+ *     forwarded to the context builder like on the REST transport.
+ *
+ * Mode is inferred: pass `port` for http, omit it for stdio.
+ */
+import * as http from 'node:http';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { buildMcpServer } from './server-builder.js';
+export function mcpTransport(options = {}) {
+    const isHttp = options.port !== undefined;
+    const mcpPath = options.path ?? '/mcp';
+    let httpServer = null;
+    let stdioServer = null;
+    const serverOptions = {
+        ...(options.name !== undefined ? { name: options.name } : {}),
+        ...(options.version !== undefined ? { version: options.version } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    };
+    return {
+        ...(options.capabilities !== undefined ? { _capabilities: options.capabilities } : {}),
+        async mount(invoke, mountOptions) {
+            if (!isHttp) {
+                // stdio — single long-lived server bound to this process's stdin/stdout
+                stdioServer = buildMcpServer(mountOptions.registry, invoke, serverOptions);
+                const transport = new StdioServerTransport();
+                await stdioServer.connect(transport);
+                console.error('[capix:mcp] serving MCP over stdio');
+                return;
+            }
+            // http — stateless Streamable HTTP: a fresh Server + transport pair per
+            // request, so concurrent clients never share JSON-RPC id space.
+            const handler = (req, res) => {
+                const pathname = (req.url ?? '/').split('?')[0] ?? '';
+                if (pathname !== mcpPath && pathname !== `${mcpPath}/`) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end('{"error":"NotFound","message":"MCP endpoint is ' + mcpPath + '"}');
+                    return;
+                }
+                const server = buildMcpServer(mountOptions.registry, invoke, serverOptions);
+                // No sessionIdGenerator — stateless mode, one transport per request.
+                const transport = new StreamableHTTPServerTransport({
+                    enableJsonResponse: true,
+                });
+                res.on('close', () => {
+                    void transport.close();
+                    void server.close();
+                });
+                server
+                    .connect(transport)
+                    .then(() => transport.handleRequest(req, res))
+                    .catch((err) => {
+                    console.error('[capix:mcp] Handler error:', err);
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end('{"error":"Internal","message":"Internal server error"}');
+                    }
+                });
+            };
+            console.log('\nCapix MCP transport starting...');
+            console.log(`  ✓ MCP (Streamable HTTP)  http://localhost:${options.port}${mcpPath}`);
+            return new Promise((resolve, reject) => {
+                httpServer = http.createServer(handler);
+                httpServer.on('error', reject);
+                httpServer.listen(options.port, options.host ?? '0.0.0.0', () => resolve());
+            });
+        },
+        async unmount() {
+            if (stdioServer !== null) {
+                await stdioServer.close();
+                stdioServer = null;
+            }
+            return new Promise((resolve, reject) => {
+                if (!httpServer)
+                    return resolve();
+                httpServer.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+                httpServer = null;
+            });
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAGnG,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAoBrD,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IAEvC,IAAI,UAAU,GAAuB,IAAI,CAAC;IAC1C,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,MAAM,aAAa,GAAqB;QACtC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;IAEF,OAAO;QACL,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAEtF,KAAK,CAAC,KAAK,CAAC,MAAgB,EAAE,YAA0B;YACtD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,wEAAwE;gBACxE,WAAW,GAAG,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBAC3E,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;gBAC7C,MAAM,WAAW,CAAC,OAAO,CAAC,SAAoC,CAAC,CAAC;gBAChE,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;gBACpD,OAAO;YACT,CAAC;YAED,wEAAwE;YACxE,gEAAgE;YAChE,MAAM,OAAO,GAAG,CAAC,GAAyB,EAAE,GAAwB,EAAQ,EAAE;gBAC5E,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACtD,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,GAAG,OAAO,GAAG,EAAE,CAAC;oBACvD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC3D,GAAG,CAAC,GAAG,CAAC,iDAAiD,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;oBAC5E,OAAO;gBACT,CAAC;gBAED,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;gBAC5E,qEAAqE;gBACrE,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;oBAClD,kBAAkB,EAAE,IAAI;iBACzB,CAAC,CAAC;gBACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;oBACnB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;oBACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;gBACtB,CAAC,CAAC,CAAC;gBAEH,MAAM;qBACH,OAAO,CAAC,SAAoC,CAAC;qBAC7C,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;qBAC7C,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;oBACtB,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC;oBACjD,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;wBACrB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;wBAC3D,GAAG,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;oBACpE,CAAC;gBACH,CAAC,CAAC,CAAC;YACP,CAAC,CAAC;YAEF,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;YACjD,OAAO,CAAC,GAAG,CAAC,+CAA+C,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC,CAAC;YAErF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;gBACxC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC/B,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9E,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,OAAO;YACX,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;gBACzB,MAAM,WAAW,CAAC,KAAK,EAAE,CAAC;gBAC1B,WAAW,GAAG,IAAI,CAAC;YACrB,CAAC;YACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,IAAI,CAAC,UAAU;oBAAE,OAAO,OAAO,EAAE,CAAC;gBAClC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;oBACvB,IAAI,GAAG;wBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;wBAChB,OAAO,EAAE,CAAC;gBACjB,CAAC,CAAC,CAAC;gBACH,UAAU,GAAG,IAAI,CAAC;YACpB,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@capixjs/transport-mcp",
+  "version": "0.1.0-alpha.15",
+  "description": "Capix MCP transport — expose capabilities as Model Context Protocol tools",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "LICENSE"
+  ],
+  "keywords": [
+    "capix",
+    "mcp",
+    "model-context-protocol",
+    "transport",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@capixjs/core": ">=0.1.0-0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "@capixjs/core": "0.1.0-alpha.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}