@nextclaw/mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw 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,125 @@
+import { McpServerDefinition, McpTransport, Config, McpServerScope } from '@nextclaw/core';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+type McpServerRecord = {
+    name: string;
+    definition: McpServerDefinition;
+};
+type McpToolCatalogEntry = {
+    qualifiedName: string;
+    serverName: string;
+    toolName: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+};
+type McpServerWarmResult = {
+    name: string;
+    ok: boolean;
+    toolCount: number;
+    error?: string;
+};
+type McpDoctorReport = {
+    name: string;
+    enabled: boolean;
+    transport: McpTransport["type"];
+    accessible: boolean;
+    toolCount: number;
+    error?: string;
+};
+type McpConfigReconcileResult = {
+    added: string[];
+    removed: string[];
+    enabled: string[];
+    disabled: string[];
+    restarted: string[];
+    warmed: McpServerWarmResult[];
+};
+type McpCatalogFilter = {
+    agentId?: string;
+};
+type McpLifecycleState = {
+    record: McpServerRecord;
+    tools: McpToolCatalogEntry[];
+    clientReady: boolean;
+    lastReadyAt?: string;
+    lastError?: string;
+};
+declare function normalizeMcpServerName(name: string): string;
+declare function readDefaultAgentId(config: Config): string;
+declare function isServerAccessibleToAgent(params: {
+    config: Config;
+    scope: McpServerScope;
+    agentId?: string;
+}): boolean;
+declare function buildQualifiedMcpToolName(serverName: string, toolName: string): string;
+declare function sanitizeMcpSegment(value: string): string;
+
+declare function listMcpServers(config: Config): McpServerRecord[];
+declare function getMcpServer(config: Config, name: string): McpServerRecord | undefined;
+
+type McpClientHandle = {
+    client: Client;
+    transport: Transport;
+};
+declare class McpClientFactory {
+    private readonly _config?;
+    constructor(_config?: Config | undefined);
+    create(record: McpServerRecord): McpClientHandle;
+}
+
+declare class McpServerLifecycleManager {
+    private readonly options;
+    private readonly pendingConnections;
+    private readonly readyConnections;
+    constructor(options: {
+        getConfig: () => Config;
+        clientFactory?: McpClientFactory;
+        now?: () => Date;
+    });
+    warmServer(record: McpServerRecord): Promise<McpLifecycleState>;
+    getCachedCatalog(serverName: string): McpToolCatalogEntry[];
+    callTool(record: McpServerRecord, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    closeAll(): Promise<void>;
+    closeServer(serverName: string): Promise<void>;
+    private ensureConnection;
+    private connect;
+    private stripConnection;
+    private normalizeToolResult;
+}
+
+declare class McpRegistryService {
+    private readonly options;
+    private readonly lifecycleManager;
+    constructor(options: {
+        getConfig: () => Config;
+        lifecycleManager?: McpServerLifecycleManager;
+    });
+    listServers(): McpServerRecord[];
+    getServer(name: string): McpServerRecord | undefined;
+    prewarmEnabledServers(): Promise<McpServerWarmResult[]>;
+    warmServer(name: string): Promise<McpServerWarmResult>;
+    reconcileConfig(params: {
+        prevConfig: Config;
+        nextConfig: Config;
+    }): Promise<McpConfigReconcileResult>;
+    listAccessibleTools(filter?: McpCatalogFilter): McpToolCatalogEntry[];
+    callTool(params: {
+        serverName: string;
+        toolName: string;
+        args: Record<string, unknown>;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+    private warmRecord;
+}
+
+declare class McpDoctorService {
+    private readonly options;
+    constructor(options: {
+        getConfig: () => Config;
+        registryService?: McpRegistryService;
+    });
+    inspect(name?: string): Promise<McpDoctorReport[]>;
+}
+
+export { type McpCatalogFilter, McpClientFactory, type McpConfigReconcileResult, type McpDoctorReport, McpDoctorService, type McpLifecycleState, McpRegistryService, McpServerLifecycleManager, type McpServerRecord, type McpServerWarmResult, type McpToolCatalogEntry, buildQualifiedMcpToolName, getMcpServer, isServerAccessibleToAgent, listMcpServers, normalizeMcpServerName, readDefaultAgentId, sanitizeMcpSegment };

package/dist/index.js

@@ -0,0 +1,452 @@
+// src/types.ts
+function normalizeMcpServerName(name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("MCP server name is required.");
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(normalized)) {
+    throw new Error("MCP server name may only contain letters, numbers, dot, underscore, and dash.");
+  }
+  return normalized;
+}
+function readDefaultAgentId(config) {
+  return config.agents.list.find((entry) => entry.default)?.id?.trim() || config.agents.list[0]?.id?.trim() || "main";
+}
+function isServerAccessibleToAgent(params) {
+  if (params.scope.allAgents) {
+    return true;
+  }
+  const targetAgentId = params.agentId?.trim() || readDefaultAgentId(params.config);
+  const explicitAgents = params.scope.agents.map((agentId) => agentId.trim()).filter(Boolean);
+  if (explicitAgents.length > 0) {
+    return explicitAgents.includes(targetAgentId);
+  }
+  return targetAgentId === readDefaultAgentId(params.config);
+}
+function buildQualifiedMcpToolName(serverName, toolName) {
+  return `mcp_${sanitizeMcpSegment(serverName)}__${sanitizeMcpSegment(toolName)}`;
+}
+function sanitizeMcpSegment(value) {
+  const sanitized = value.trim().replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+  return sanitized || "unnamed";
+}
+
+// src/config/mcp-config-normalizer.ts
+function listMcpServers(config) {
+  return Object.entries(config.mcp.servers).map(([name, definition]) => ({
+    name: normalizeMcpServerName(name),
+    definition
+  })).sort((left, right) => left.name.localeCompare(right.name));
+}
+function getMcpServer(config, name) {
+  const normalizedName = normalizeMcpServerName(name);
+  const definition = config.mcp.servers[normalizedName];
+  if (!definition) {
+    return void 0;
+  }
+  return {
+    name: normalizedName,
+    definition
+  };
+}
+
+// src/client/mcp-client-factory.ts
+import { Agent, fetch as undiciFetch } from "undici";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function createClient() {
+  return new Client({
+    name: "nextclaw-mcp-client",
+    version: "0.1.0"
+  });
+}
+function buildFetch(transport) {
+  const timeoutMs = transport.timeoutMs;
+  const insecureAgent = transport.verifyTls ? null : new Agent({
+    connect: {
+      rejectUnauthorized: false
+    }
+  });
+  return async (input, init) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await undiciFetch(input, {
+        ...init,
+        dispatcher: insecureAgent ?? init?.dispatcher,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+}
+function createStdioTransport(transport) {
+  return new StdioClientTransport({
+    command: transport.command,
+    args: transport.args,
+    cwd: transport.cwd,
+    env: Object.keys(transport.env).length > 0 ? transport.env : void 0,
+    stderr: transport.stderr
+  });
+}
+function createHttpTransport(transport) {
+  return new StreamableHTTPClientTransport(new URL(transport.url), {
+    requestInit: {
+      headers: transport.headers
+    },
+    fetch: buildFetch(transport)
+  });
+}
+function createSseTransport(transport) {
+  return new SSEClientTransport(new URL(transport.url), {
+    requestInit: {
+      headers: transport.headers
+    },
+    eventSourceInit: {
+      fetch: buildFetch(transport),
+      headers: transport.headers
+    },
+    fetch: buildFetch(transport)
+  });
+}
+var McpClientFactory = class {
+  constructor(_config) {
+    this._config = _config;
+    void this._config;
+  }
+  create(record) {
+    const transport = (() => {
+      switch (record.definition.transport.type) {
+        case "stdio":
+          return createStdioTransport(record.definition.transport);
+        case "http":
+          return createHttpTransport(record.definition.transport);
+        case "sse":
+          return createSseTransport(record.definition.transport);
+        default:
+          throw new Error(`Unsupported MCP transport: ${String(record.definition.transport.type)}`);
+      }
+    })();
+    return {
+      client: createClient(),
+      transport
+    };
+  }
+};
+
+// src/lifecycle/mcp-server-lifecycle-manager.ts
+var McpServerLifecycleManager = class {
+  constructor(options) {
+    this.options = options;
+  }
+  pendingConnections = /* @__PURE__ */ new Map();
+  readyConnections = /* @__PURE__ */ new Map();
+  async warmServer(record) {
+    const connection = await this.ensureConnection(record);
+    return this.stripConnection(connection);
+  }
+  getCachedCatalog(serverName) {
+    return this.readyConnections.get(serverName)?.tools ?? [];
+  }
+  async callTool(record, toolName, args) {
+    const connection = await this.ensureConnection(record);
+    const result = await connection.client.callTool({
+      name: toolName,
+      arguments: args
+    });
+    return this.normalizeToolResult(result);
+  }
+  async closeAll() {
+    const pending = await Promise.allSettled(this.pendingConnections.values());
+    for (const result of pending) {
+      if (result.status === "fulfilled") {
+        this.readyConnections.set(result.value.record.name, result.value);
+      }
+    }
+    for (const connection of this.readyConnections.values()) {
+      await connection.transport.close().catch(() => {
+      });
+    }
+    this.pendingConnections.clear();
+    this.readyConnections.clear();
+  }
+  async closeServer(serverName) {
+    const ready = this.readyConnections.get(serverName);
+    this.readyConnections.delete(serverName);
+    const pending = this.pendingConnections.get(serverName);
+    this.pendingConnections.delete(serverName);
+    if (ready) {
+      await ready.transport.close().catch(() => {
+      });
+    }
+    if (!pending) {
+      return;
+    }
+    const result = await Promise.allSettled([pending]);
+    const settled = result[0];
+    if (settled?.status === "fulfilled") {
+      await settled.value.transport.close().catch(() => {
+      });
+    }
+    this.readyConnections.delete(serverName);
+    this.pendingConnections.delete(serverName);
+  }
+  async ensureConnection(record) {
+    const ready = this.readyConnections.get(record.name);
+    if (ready) {
+      return ready;
+    }
+    const existing = this.pendingConnections.get(record.name);
+    if (existing) {
+      return existing;
+    }
+    const task = this.connect(record);
+    this.pendingConnections.set(record.name, task);
+    try {
+      const connection = await task;
+      this.readyConnections.set(record.name, connection);
+      this.pendingConnections.delete(record.name);
+      return connection;
+    } catch (error) {
+      this.pendingConnections.delete(record.name);
+      throw error;
+    }
+  }
+  async connect(record) {
+    const config = this.options.getConfig();
+    const clientFactory = this.options.clientFactory ?? new McpClientFactory(config);
+    const { client, transport } = clientFactory.create(record);
+    await client.connect(transport);
+    const listedTools = await client.listTools();
+    const tools = listedTools.tools.map((tool) => ({
+      qualifiedName: buildQualifiedMcpToolName(record.name, tool.name),
+      serverName: record.name,
+      toolName: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema
+    }));
+    const now = (this.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+    return {
+      record,
+      tools,
+      clientReady: true,
+      lastReadyAt: now,
+      client,
+      transport
+    };
+  }
+  stripConnection(connection) {
+    return {
+      record: connection.record,
+      tools: connection.tools,
+      clientReady: connection.clientReady,
+      lastReadyAt: connection.lastReadyAt,
+      lastError: connection.lastError
+    };
+  }
+  normalizeToolResult(result) {
+    if ("toolResult" in result) {
+      return result.toolResult;
+    }
+    return {
+      content: result.content,
+      structuredContent: result.structuredContent,
+      isError: result.isError ?? false
+    };
+  }
+};
+
+// src/registry/mcp-registry-service.ts
+var McpRegistryService = class {
+  constructor(options) {
+    this.options = options;
+    this.lifecycleManager = this.options.lifecycleManager ?? new McpServerLifecycleManager({
+      getConfig: this.options.getConfig
+    });
+  }
+  lifecycleManager;
+  listServers() {
+    return listMcpServers(this.options.getConfig());
+  }
+  getServer(name) {
+    return getMcpServer(this.options.getConfig(), name);
+  }
+  async prewarmEnabledServers() {
+    const results = await Promise.all(
+      this.listServers().filter((record) => record.definition.enabled).map(async (record) => {
+        try {
+          const state = await this.lifecycleManager.warmServer(record);
+          return {
+            name: record.name,
+            ok: true,
+            toolCount: state.tools.length
+          };
+        } catch (error) {
+          return {
+            name: record.name,
+            ok: false,
+            toolCount: 0,
+            error: toErrorMessage(error)
+          };
+        }
+      })
+    );
+    return results.sort((left, right) => left.name.localeCompare(right.name));
+  }
+  async warmServer(name) {
+    const server = this.getServer(name);
+    if (!server) {
+      throw new Error(`Unknown MCP server: ${name}`);
+    }
+    try {
+      const state = await this.lifecycleManager.warmServer(server);
+      return {
+        name: server.name,
+        ok: true,
+        toolCount: state.tools.length
+      };
+    } catch (error) {
+      return {
+        name: server.name,
+        ok: false,
+        toolCount: 0,
+        error: toErrorMessage(error)
+      };
+    }
+  }
+  async reconcileConfig(params) {
+    const previousServers = new Map(listMcpServers(params.prevConfig).map((record) => [record.name, record]));
+    const nextServers = new Map(listMcpServers(params.nextConfig).map((record) => [record.name, record]));
+    const serverNames = Array.from(/* @__PURE__ */ new Set([...previousServers.keys(), ...nextServers.keys()])).sort(
+      (left, right) => left.localeCompare(right)
+    );
+    const result = {
+      added: [],
+      removed: [],
+      enabled: [],
+      disabled: [],
+      restarted: [],
+      warmed: []
+    };
+    for (const serverName of serverNames) {
+      const previous = previousServers.get(serverName);
+      const next = nextServers.get(serverName);
+      if (!next) {
+        await this.lifecycleManager.closeServer(serverName);
+        result.removed.push(serverName);
+        continue;
+      }
+      if (!previous) {
+        result.added.push(serverName);
+        if (next.definition.enabled) {
+          result.warmed.push(await this.warmRecord(next));
+        }
+        continue;
+      }
+      if (previous.definition.enabled && !next.definition.enabled) {
+        await this.lifecycleManager.closeServer(serverName);
+        result.disabled.push(serverName);
+        continue;
+      }
+      if (!previous.definition.enabled && next.definition.enabled) {
+        result.enabled.push(serverName);
+        result.warmed.push(await this.warmRecord(next));
+        continue;
+      }
+      if (hasReconnectRelevantChange(previous.definition, next.definition)) {
+        await this.lifecycleManager.closeServer(serverName);
+        result.restarted.push(serverName);
+        if (next.definition.enabled) {
+          result.warmed.push(await this.warmRecord(next));
+        }
+      }
+    }
+    return result;
+  }
+  listAccessibleTools(filter = {}) {
+    const config = this.options.getConfig();
+    return this.listServers().filter((record) => record.definition.enabled).filter(
+      (record) => isServerAccessibleToAgent({
+        config,
+        scope: record.definition.scope,
+        agentId: filter.agentId
+      })
+    ).flatMap((record) => this.lifecycleManager.getCachedCatalog(record.name)).sort((left, right) => left.qualifiedName.localeCompare(right.qualifiedName));
+  }
+  async callTool(params) {
+    const server = this.getServer(params.serverName);
+    if (!server) {
+      throw new Error(`Unknown MCP server: ${params.serverName}`);
+    }
+    return this.lifecycleManager.callTool(server, params.toolName, params.args);
+  }
+  async close() {
+    await this.lifecycleManager.closeAll();
+  }
+  async warmRecord(record) {
+    try {
+      const state = await this.lifecycleManager.warmServer(record);
+      return {
+        name: record.name,
+        ok: true,
+        toolCount: state.tools.length
+      };
+    } catch (error) {
+      return {
+        name: record.name,
+        ok: false,
+        toolCount: 0,
+        error: toErrorMessage(error)
+      };
+    }
+  }
+};
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function hasReconnectRelevantChange(left, right) {
+  return JSON.stringify(left.transport) !== JSON.stringify(right.transport);
+}
+
+// src/doctor/mcp-doctor-service.ts
+var McpDoctorService = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async inspect(name) {
+    const registry = this.options.registryService ?? new McpRegistryService({
+      getConfig: this.options.getConfig
+    });
+    const specificServer = name ? registry.getServer(name) : void 0;
+    const servers = specificServer ? [specificServer] : name ? [] : registry.listServers();
+    return await Promise.all(
+      servers.map(async (server) => {
+        const warmResult = await registry.warmServer(server.name);
+        return {
+          name: server.name,
+          enabled: server.definition.enabled,
+          transport: server.definition.transport.type,
+          accessible: warmResult.ok,
+          toolCount: warmResult.toolCount,
+          ...warmResult.error ? { error: warmResult.error } : {}
+        };
+      })
+    );
+  }
+};
+export {
+  McpClientFactory,
+  McpDoctorService,
+  McpRegistryService,
+  McpServerLifecycleManager,
+  buildQualifiedMcpToolName,
+  getMcpServer,
+  isServerAccessibleToAgent,
+  listMcpServers,
+  normalizeMcpServerName,
+  readDefaultAgentId,
+  sanitizeMcpSegment
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@nextclaw/mcp",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Platform-level MCP registry, lifecycle, and diagnostics for NextClaw.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "undici": "^6.21.0",
+    "@nextclaw/core": "0.9.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "prettier": "^3.3.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "lint": "cd ../.. && pnpm exec eslint packages/nextclaw-mcp --config eslint.config.mjs",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}