@nestjs-adk/mcp 0.0.1

package/README.md

@@ -0,0 +1,13 @@
+# @nestjs-adk/mcp
+
+Consume external MCP servers as agent tools for [`@nestjs-adk/core`](https://www.npmjs.com/package/@nestjs-adk/core), via the official `@modelcontextprotocol/sdk` (stdio, streamable HTTP, SSE).
+
+```ts
+McpModule.forRoot({ servers: [{ name: "github", transport: { type: "stdio", command: "npx", args: [...] } }] })
+
+@Agent({ ..., tools: [toolset("github", ["create_issue"])] }) // the server's catalog becomes tools (JSON Schema → Zod)
+```
+
+The catalog is cached at boot (fail-fast; `optional: true` for non-critical servers). Runtime tool failures return as `{ error }` to the LLM; connection errors become typed `McpConnectionError`s.
+
+Full documentation: [github.com/gabrieljsilva/nestjs-adk](https://github.com/gabrieljsilva/nestjs-adk)

package/dist/index.cjs

@@ -0,0 +1,215 @@
+'use strict';
+
+var core = require('@nestjs-adk/core');
+var index_js = require('@modelcontextprotocol/sdk/client/index.js');
+var sse_js = require('@modelcontextprotocol/sdk/client/sse.js');
+var stdio_js = require('@modelcontextprotocol/sdk/client/stdio.js');
+var streamableHttp_js = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
+var common = require('@nestjs/common');
+var zod = require('zod');
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+function __param(paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+}
+
+function __metadata(metadataKey, metadataValue) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+function jsonSchemaToZod(schema) {
+    const root = (schema ?? {});
+    const shape = {};
+    const required = new Set(root.required ?? []);
+    for (const [key, property] of Object.entries(root.properties ?? {})) {
+        let type = convert(property);
+        if (!required.has(key))
+            type = type.optional();
+        shape[key] = type;
+    }
+    return zod.z.object(shape);
+}
+function convert(schema) {
+    let type;
+    if (schema.enum) {
+        type = zod.z.enum(schema.enum.map(String));
+    }
+    else {
+        switch (schema.type) {
+            case "string":
+                type = zod.z.string();
+                break;
+            case "number":
+                type = zod.z.number();
+                break;
+            case "integer":
+                type = zod.z.number().int();
+                break;
+            case "boolean":
+                type = zod.z.boolean();
+                break;
+            case "array":
+                type = zod.z.array(schema.items ? convert(schema.items) : zod.z.any());
+                break;
+            case "object":
+                type = jsonSchemaToZod(schema);
+                break;
+            default:
+                type = zod.z.any();
+        }
+    }
+    return schema.description ? type.describe(schema.description) : type;
+}
+
+const MCP_OPTIONS = Symbol("adk:mcp-options");
+
+var McpClient_1;
+exports.McpClient = McpClient_1 = class McpClient extends core.ToolsetResolver {
+    constructor(options) {
+        super();
+        this.options = options;
+        this.logger = new common.Logger(McpClient_1.name);
+        this.catalogs = new Map();
+    }
+    async onModuleInit() {
+        for (const server of this.options.servers) {
+            try {
+                await this.connect(server);
+            }
+            catch (error) {
+                if (server.optional) {
+                    this.logger.warn(`MCP server "${server.name}" unavailable (optional) — tools ignored.`);
+                    continue;
+                }
+                throw new core.McpConnectionError(server.name, error);
+            }
+        }
+    }
+    async onModuleDestroy() {
+        for (const { client } of this.catalogs.values()) {
+            await client.close().catch(() => undefined);
+        }
+    }
+    async resolve(ref) {
+        const catalog = this.catalogs.get(ref.__adkToolset);
+        if (!catalog) {
+            const configured = this.options.servers.some((server) => server.name === ref.__adkToolset);
+            if (configured)
+                return [];
+            throw new core.McpConnectionError(ref.__adkToolset, new Error("server is not configured in McpModule.forRoot"));
+        }
+        const tools = ref.filter ? catalog.tools.filter((tool) => ref.filter?.includes(tool.name)) : catalog.tools;
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            schema: jsonSchemaToZod(tool.inputSchema),
+            execute: async (input) => this.callTool(catalog.client, tool.name, input),
+        }));
+    }
+    async callTool(client, name, input) {
+        try {
+            const result = await client.callTool({ name, arguments: (input ?? {}) });
+            const texts = (result.content ?? [])
+                .filter((part) => part.type === "text")
+                .map((part) => part.text ?? "");
+            if (result.isError)
+                return { error: texts.join("\n") || `MCP tool "${name}" failed.` };
+            if (result.structuredContent)
+                return result.structuredContent;
+            return texts.length === 1 ? texts[0] : texts.join("\n");
+        }
+        catch (error) {
+            return { error: `MCP tool "${name}" failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    async connect(server) {
+        const client = new index_js.Client({ name: "nestjs-adk", version: "1.0.0" });
+        await client.connect(this.createTransport(server.transport));
+        const { tools } = await client.listTools();
+        this.catalogs.set(server.name, {
+            client,
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema,
+            })),
+        });
+        this.logger.log(`MCP server "${server.name}" connected — ${tools.length} tools in the catalog.`);
+    }
+    createTransport(transport) {
+        switch (transport.type) {
+            case "stdio":
+                return new stdio_js.StdioClientTransport({
+                    command: transport.command,
+                    args: transport.args,
+                    env: transport.env ? { ...cleanEnv(process.env), ...transport.env } : undefined,
+                });
+            case "http":
+                return new streamableHttp_js.StreamableHTTPClientTransport(new URL(transport.url), {
+                    requestInit: { headers: transport.headers },
+                });
+            case "sse":
+                return new sse_js.SSEClientTransport(new URL(transport.url), { requestInit: { headers: transport.headers } });
+        }
+    }
+};
+exports.McpClient = McpClient_1 = __decorate([
+    common.Injectable(),
+    __param(0, common.Inject(MCP_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], exports.McpClient);
+function cleanEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter(([, value]) => value !== undefined));
+}
+
+var McpModule_1;
+exports.McpModule = McpModule_1 = class McpModule {
+    static forRoot(options) {
+        return {
+            module: McpModule_1,
+            providers: [
+                { provide: MCP_OPTIONS, useValue: options },
+                exports.McpClient,
+                { provide: core.ToolsetResolver, useExisting: exports.McpClient },
+            ],
+            exports: [core.ToolsetResolver, exports.McpClient],
+        };
+    }
+};
+exports.McpModule = McpModule_1 = __decorate([
+    common.Global(),
+    common.Module({})
+], exports.McpModule);
+
+const mcpTools = core.toolset;
+
+exports.jsonSchemaToZod = jsonSchemaToZod;
+exports.mcpTools = mcpTools;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { toolset } from "@nestjs-adk/core";
+export { McpClient } from "./lib/mcp-client";
+export { McpModule } from "./lib/mcp.module";
+export type { McpModuleOptions, McpServerConfig, McpTransportConfig } from "./lib/mcp-options";
+export { jsonSchemaToZod } from "./lib/json-schema-to-zod";
+export declare const mcpTools: typeof toolset;

package/dist/index.mjs

@@ -0,0 +1,212 @@
+import { ToolsetResolver, McpConnectionError, toolset } from '@nestjs-adk/core';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Injectable, Inject, Logger, Global, Module } from '@nestjs/common';
+import { z } from 'zod';
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+function __param(paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+}
+
+function __metadata(metadataKey, metadataValue) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+function jsonSchemaToZod(schema) {
+    const root = (schema ?? {});
+    const shape = {};
+    const required = new Set(root.required ?? []);
+    for (const [key, property] of Object.entries(root.properties ?? {})) {
+        let type = convert(property);
+        if (!required.has(key))
+            type = type.optional();
+        shape[key] = type;
+    }
+    return z.object(shape);
+}
+function convert(schema) {
+    let type;
+    if (schema.enum) {
+        type = z.enum(schema.enum.map(String));
+    }
+    else {
+        switch (schema.type) {
+            case "string":
+                type = z.string();
+                break;
+            case "number":
+                type = z.number();
+                break;
+            case "integer":
+                type = z.number().int();
+                break;
+            case "boolean":
+                type = z.boolean();
+                break;
+            case "array":
+                type = z.array(schema.items ? convert(schema.items) : z.any());
+                break;
+            case "object":
+                type = jsonSchemaToZod(schema);
+                break;
+            default:
+                type = z.any();
+        }
+    }
+    return schema.description ? type.describe(schema.description) : type;
+}
+
+const MCP_OPTIONS = Symbol("adk:mcp-options");
+
+var McpClient_1;
+let McpClient = McpClient_1 = class McpClient extends ToolsetResolver {
+    constructor(options) {
+        super();
+        this.options = options;
+        this.logger = new Logger(McpClient_1.name);
+        this.catalogs = new Map();
+    }
+    async onModuleInit() {
+        for (const server of this.options.servers) {
+            try {
+                await this.connect(server);
+            }
+            catch (error) {
+                if (server.optional) {
+                    this.logger.warn(`MCP server "${server.name}" unavailable (optional) — tools ignored.`);
+                    continue;
+                }
+                throw new McpConnectionError(server.name, error);
+            }
+        }
+    }
+    async onModuleDestroy() {
+        for (const { client } of this.catalogs.values()) {
+            await client.close().catch(() => undefined);
+        }
+    }
+    async resolve(ref) {
+        const catalog = this.catalogs.get(ref.__adkToolset);
+        if (!catalog) {
+            const configured = this.options.servers.some((server) => server.name === ref.__adkToolset);
+            if (configured)
+                return [];
+            throw new McpConnectionError(ref.__adkToolset, new Error("server is not configured in McpModule.forRoot"));
+        }
+        const tools = ref.filter ? catalog.tools.filter((tool) => ref.filter?.includes(tool.name)) : catalog.tools;
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            schema: jsonSchemaToZod(tool.inputSchema),
+            execute: async (input) => this.callTool(catalog.client, tool.name, input),
+        }));
+    }
+    async callTool(client, name, input) {
+        try {
+            const result = await client.callTool({ name, arguments: (input ?? {}) });
+            const texts = (result.content ?? [])
+                .filter((part) => part.type === "text")
+                .map((part) => part.text ?? "");
+            if (result.isError)
+                return { error: texts.join("\n") || `MCP tool "${name}" failed.` };
+            if (result.structuredContent)
+                return result.structuredContent;
+            return texts.length === 1 ? texts[0] : texts.join("\n");
+        }
+        catch (error) {
+            return { error: `MCP tool "${name}" failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    async connect(server) {
+        const client = new Client({ name: "nestjs-adk", version: "1.0.0" });
+        await client.connect(this.createTransport(server.transport));
+        const { tools } = await client.listTools();
+        this.catalogs.set(server.name, {
+            client,
+            tools: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema,
+            })),
+        });
+        this.logger.log(`MCP server "${server.name}" connected — ${tools.length} tools in the catalog.`);
+    }
+    createTransport(transport) {
+        switch (transport.type) {
+            case "stdio":
+                return new StdioClientTransport({
+                    command: transport.command,
+                    args: transport.args,
+                    env: transport.env ? { ...cleanEnv(process.env), ...transport.env } : undefined,
+                });
+            case "http":
+                return new StreamableHTTPClientTransport(new URL(transport.url), {
+                    requestInit: { headers: transport.headers },
+                });
+            case "sse":
+                return new SSEClientTransport(new URL(transport.url), { requestInit: { headers: transport.headers } });
+        }
+    }
+};
+McpClient = McpClient_1 = __decorate([
+    Injectable(),
+    __param(0, Inject(MCP_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], McpClient);
+function cleanEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter(([, value]) => value !== undefined));
+}
+
+var McpModule_1;
+let McpModule = McpModule_1 = class McpModule {
+    static forRoot(options) {
+        return {
+            module: McpModule_1,
+            providers: [
+                { provide: MCP_OPTIONS, useValue: options },
+                McpClient,
+                { provide: ToolsetResolver, useExisting: McpClient },
+            ],
+            exports: [ToolsetResolver, McpClient],
+        };
+    }
+};
+McpModule = McpModule_1 = __decorate([
+    Global(),
+    Module({})
+], McpModule);
+
+const mcpTools = toolset;
+
+export { McpClient, McpModule, jsonSchemaToZod, mcpTools };

package/dist/lib/json-schema-to-zod.d.ts

@@ -0,0 +1,2 @@
+import type { AnyZodObject } from "@nestjs-adk/core";
+export declare function jsonSchemaToZod(schema: unknown): AnyZodObject;

package/dist/lib/mcp-client.d.ts

@@ -0,0 +1,15 @@
+import { type ResolvedTool, type ToolsetRef, ToolsetResolver } from "@nestjs-adk/core";
+import { type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
+import { type McpModuleOptions } from "./mcp-options";
+export declare class McpClient extends ToolsetResolver implements OnModuleInit, OnModuleDestroy {
+    private readonly options;
+    private readonly logger;
+    private readonly catalogs;
+    constructor(options: McpModuleOptions);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    resolve(ref: ToolsetRef): Promise<ResolvedTool[]>;
+    private callTool;
+    private connect;
+    private createTransport;
+}

package/dist/lib/mcp-options.d.ts

@@ -0,0 +1,23 @@
+export type McpTransportConfig = {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+};
+export interface McpServerConfig {
+    name: string;
+    transport: McpTransportConfig;
+    optional?: boolean;
+}
+export interface McpModuleOptions {
+    servers: McpServerConfig[];
+}
+export declare const MCP_OPTIONS: unique symbol;

package/dist/lib/mcp.module.d.ts

@@ -0,0 +1,5 @@
+import { type DynamicModule } from "@nestjs/common";
+import { type McpModuleOptions } from "./mcp-options";
+export declare class McpModule {
+    static forRoot(options: McpModuleOptions): DynamicModule;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@nestjs-adk/mcp",
+	"version": "0.0.1",
+	"description": "MCP client integration for nestjs-adk: consume external MCP servers as agent tools.",
+	"license": "MIT",
+	"sideEffects": false,
+	"main": "dist/index.cjs",
+	"module": "dist/index.mjs",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": ["dist"],
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"prebuild": "rimraf -g dist",
+		"build": "rollup -c"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.0"
+	},
+	"peerDependencies": {
+		"@nestjs-adk/core": "^0.0.1",
+		"@nestjs/common": "^10.0.0 || ^11.0.0",
+		"@nestjs/core": "^10.0.0 || ^11.0.0",
+		"zod": "^3.23.0 || ^4.0.0"
+	},
+	"devDependencies": {
+		"@nestjs-adk/core": "^0.0.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}