@nebutra/mcp 0.1.0 → 0.1.2

package/dist/chunk-73DKWF2B.js

@@ -0,0 +1,704 @@
+// src/registry/serverRegistry.ts
+var MCPServerRegistry = class {
+  servers = /* @__PURE__ */ new Map();
+  toolIndex = /* @__PURE__ */ new Map();
+  // tool name -> server id
+  /**
+   * Register an MCP server
+   */
+  register(config) {
+    this.servers.set(config.id, config);
+    for (const tool of config.tools) {
+      const qualifiedName = `${config.id}:${tool.name}`;
+      this.toolIndex.set(qualifiedName, config.id);
+      if (!this.toolIndex.has(tool.name)) {
+        this.toolIndex.set(tool.name, config.id);
+      }
+    }
+  }
+  /**
+   * Unregister an MCP server
+   */
+  unregister(serverId) {
+    const server = this.servers.get(serverId);
+    if (!server) return false;
+    for (const tool of server.tools) {
+      const qualifiedName = `${serverId}:${tool.name}`;
+      this.toolIndex.delete(qualifiedName);
+      if (this.toolIndex.get(tool.name) === serverId) {
+        this.toolIndex.delete(tool.name);
+      }
+    }
+    this.servers.delete(serverId);
+    return true;
+  }
+  /**
+   * Get server by ID
+   */
+  getServer(serverId) {
+    return this.servers.get(serverId);
+  }
+  /**
+   * Find server by tool name
+   */
+  findServerByTool(toolName) {
+    const serverId = this.toolIndex.get(toolName);
+    if (!serverId) return void 0;
+    return this.servers.get(serverId);
+  }
+  /**
+   * Get all registered servers
+   */
+  getAllServers() {
+    return Array.from(this.servers.values());
+  }
+  /**
+   * Get all available tools
+   */
+  getAllTools() {
+    const tools = [];
+    for (const server of this.servers.values()) {
+      for (const tool of server.tools) {
+        tools.push({ ...tool, serverId: server.id });
+      }
+    }
+    return tools;
+  }
+  /**
+   * Check if a context has access to a server
+   */
+  canAccess(serverId, context) {
+    const server = this.servers.get(serverId);
+    if (!server) return false;
+    if (server.allowedPlans && server.allowedPlans.length > 0) {
+      if (!context.plan || !server.allowedPlans.includes(context.plan)) {
+        return false;
+      }
+    }
+    if (server.allowedTenants && server.allowedTenants.length > 0) {
+      if (!context.tenantId || !server.allowedTenants.includes(context.tenantId)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Check whether a context can execute a specific tool. Tool-level policy
+   * narrows the server policy and supports tenant, plan, and permission gates.
+   */
+  canAccessTool(toolName, context) {
+    const server = this.findServerByTool(toolName);
+    if (!server || !this.canAccess(server.id, context)) return false;
+    const tool = this.findTool(server, toolName);
+    if (!tool) return false;
+    if (tool.allowedPlans && tool.allowedPlans.length > 0) {
+      if (!context.plan || !tool.allowedPlans.includes(context.plan)) return false;
+    }
+    if (tool.allowedTenants && tool.allowedTenants.length > 0) {
+      if (!context.tenantId || !tool.allowedTenants.includes(context.tenantId)) return false;
+    }
+    if (tool.requiredPermissions && tool.requiredPermissions.length > 0) {
+      const permissions = new Set(context.permissions ?? []);
+      if (!tool.requiredPermissions.every((permission) => permissions.has(permission))) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Get tools accessible by a context
+   */
+  getAccessibleTools(context) {
+    const tools = [];
+    for (const server of this.servers.values()) {
+      if (this.canAccess(server.id, context)) {
+        for (const tool of server.tools) {
+          if (this.canAccessTool(`${server.id}:${tool.name}`, context)) {
+            tools.push({ ...tool, serverId: server.id });
+          }
+        }
+      }
+    }
+    return tools;
+  }
+  findTool(server, toolName) {
+    return server.tools.find(
+      (tool) => tool.name === toolName || `${server.id}:${tool.name}` === toolName
+    );
+  }
+};
+var serverRegistry = new MCPServerRegistry();
+
+// src/client/mcpClient.ts
+var MCPClient = class {
+  constructor(registry = serverRegistry) {
+    this.registry = registry;
+  }
+  requestCounter = 0;
+  /**
+   * Execute a tool by name
+   */
+  async executeTool(toolName, args, context) {
+    const startTime = Date.now();
+    const server = this.registry.findServerByTool(toolName);
+    if (!server) {
+      return {
+        success: false,
+        error: `Tool not found: ${toolName}`,
+        duration: Date.now() - startTime
+      };
+    }
+    if (!this.registry.canAccessTool(toolName, context)) {
+      return {
+        success: false,
+        error: `Access denied to tool: ${toolName}`,
+        duration: Date.now() - startTime
+      };
+    }
+    try {
+      const result = await this.executeOnServer(server, toolName, args, context);
+      return {
+        success: true,
+        result,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      };
+    }
+  }
+  /**
+   * Execute tool on a specific server
+   */
+  async executeOnServer(server, toolName, args, context) {
+    const requestId = `${context.requestId}-${++this.requestCounter}`;
+    switch (server.transport) {
+      case "http":
+        return this.executeHttp(server, toolName, args, requestId);
+      case "websocket":
+        return this.executeWebSocket(server, toolName, args, requestId);
+      case "local":
+        return this.executeLocal(server, toolName, args, context);
+      case "stdio":
+        throw new Error("stdio transport not supported in browser/serverless");
+      default:
+        throw new Error(`Unknown transport: ${server.transport}`);
+    }
+  }
+  /**
+   * Execute via HTTP transport
+   */
+  async executeHttp(server, toolName, args, requestId) {
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Request-ID": requestId
+    };
+    if (server.authentication?.type === "bearer") {
+      const token = process.env[`MCP_${server.id.toUpperCase()}_TOKEN`];
+      if (token) {
+        headers.Authorization = `Bearer ${token}`;
+      }
+    } else if (server.authentication?.type === "api-key") {
+      const apiKey = process.env[`MCP_${server.id.toUpperCase()}_KEY`];
+      const headerName = server.authentication.headerName || "X-API-Key";
+      if (apiKey) {
+        headers[headerName] = apiKey;
+      }
+    }
+    const response = await fetch(server.endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: requestId,
+        method: "tools/call",
+        params: {
+          name: toolName,
+          arguments: args
+        }
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (data.error) {
+      throw new Error(data.error.message || "Unknown MCP error");
+    }
+    return data.result;
+  }
+  /**
+   * Execute via WebSocket transport
+   */
+  async executeWebSocket(_server, _toolName, _args, _requestId) {
+    throw new Error("WebSocket transport not yet implemented");
+  }
+  async executeLocal(server, toolName, args, context) {
+    const shortName = toolName.startsWith(`${server.id}:`) ? toolName.slice(server.id.length + 1) : toolName;
+    const handler = server.handlers?.[shortName] ?? server.handlers?.[toolName];
+    if (!handler) {
+      throw new Error(`No local handler registered for tool: ${toolName}`);
+    }
+    return handler(args, context);
+  }
+  /**
+   * List available tools for a context
+   */
+  listTools(context) {
+    return this.registry.getAccessibleTools(context);
+  }
+  /**
+   * Get tool definition
+   */
+  getTool(toolName, context) {
+    const server = this.registry.findServerByTool(toolName);
+    if (!server) return void 0;
+    if (!this.registry.canAccessTool(toolName, context)) {
+      return void 0;
+    }
+    return server.tools.find((t) => t.name === toolName || `${server.id}:${t.name}` === toolName);
+  }
+};
+var mcpClient = new MCPClient();
+
+// src/consent.ts
+function consentKey(grant) {
+  return [grant.tenantId, grant.userId ?? "*", grant.serverId, grant.toolName].join(":");
+}
+var InMemoryToolConsentStore = class {
+  #grants = /* @__PURE__ */ new Map();
+  async grant(grant) {
+    this.#grants.set(consentKey(grant), { ...grant, scopes: [...grant.scopes] });
+  }
+  async hasConsent(grant) {
+    const exact = this.#grants.get(consentKey(grant));
+    const wildcard = this.#grants.get(
+      consentKey({
+        tenantId: grant.tenantId,
+        serverId: grant.serverId,
+        toolName: grant.toolName
+      })
+    );
+    const existing = exact ?? wildcard;
+    if (!existing) return false;
+    const scopes = new Set(existing.scopes);
+    return grant.scopes.every((scope) => scopes.has(scope));
+  }
+  async list(tenantId) {
+    return Array.from(this.#grants.values()).filter(
+      (grant) => tenantId === void 0 || grant.tenantId === tenantId
+    );
+  }
+};
+
+// src/debug.ts
+import {
+  appendCapabilityDebug,
+  capabilityDebugPath,
+  readCapabilityDebug
+} from "@nebutra/capability-kit/debug";
+function toolDebugPath() {
+  return capabilityDebugPath("tool-protocol");
+}
+async function appendToolDebug(entry) {
+  await appendCapabilityDebug("tool-protocol", entry);
+}
+async function readToolDebug(limit = 10) {
+  return readCapabilityDebug("tool-protocol", { limit });
+}
+
+// src/host.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { CapabilityError } from "@nebutra/errors";
+function shortToolName(serverId, toolName) {
+  return toolName.startsWith(`${serverId}:`) ? toolName.slice(serverId.length + 1) : toolName;
+}
+function requireManifest(serverId, manifest) {
+  if (!manifest || manifest.scopes.length === 0 || manifest.version.length === 0) {
+    throw new CapabilityError("tool-protocol", "MCP server manifest is required", {
+      suggestion: "Register every connected server with name, version, and declared scopes.",
+      metadata: { serverId },
+      statusCode: 400
+    });
+  }
+  return manifest;
+}
+function toJsonObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : { value };
+}
+var McpHost = class {
+  #registry;
+  #client;
+  #consent;
+  #traceStore;
+  #eventLog;
+  #sdkClients = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.#registry = options.registry ?? new MCPServerRegistry();
+    this.#client = new MCPClient(this.#registry);
+    this.#consent = options.consent ?? new InMemoryToolConsentStore();
+    this.#traceStore = options.traceStore;
+    this.#eventLog = options.eventLog;
+  }
+  get registry() {
+    return this.#registry;
+  }
+  connectLocal(config) {
+    const manifest = requireManifest(config.id, config.manifest);
+    this.#registry.register({
+      id: config.id,
+      name: config.name,
+      description: config.description,
+      endpoint: `local://${config.id}`,
+      transport: "local",
+      manifest,
+      tools: [...config.tools],
+      handlers: config.handlers,
+      ...config.allowedPlans !== void 0 && { allowedPlans: [...config.allowedPlans] },
+      ...config.allowedTenants !== void 0 && { allowedTenants: [...config.allowedTenants] }
+    });
+  }
+  async connectStdio(command, args, options) {
+    const transport = new StdioClientTransport({ command, args: [...args] });
+    await this.#connectSdkClient(options, transport, `stdio://${command}`);
+  }
+  async connectStreamableHttp(endpoint, options) {
+    const transport = new StreamableHTTPClientTransport(
+      new URL(endpoint),
+      options.headers !== void 0 ? { requestInit: { headers: options.headers } } : {}
+    );
+    await this.#connectSdkClient(options, transport, endpoint);
+  }
+  async callTool(toolName, args, context) {
+    const start = Date.now();
+    const server = this.#registry.findServerByTool(toolName);
+    const serverId = server?.id;
+    const shortName = serverId ? shortToolName(serverId, toolName) : toolName;
+    const span = this.#traceStore?.start("tool", toolName, {
+      traceId: context.requestId,
+      tenantId: context.tenantId,
+      serverId
+    });
+    if (!context.tenantId) {
+      const result2 = {
+        success: false,
+        error: "Missing tenant context; suggestion: call tools with a tenantId.",
+        duration: Date.now() - start
+      };
+      await this.#recordCall(toolName, shortName, serverId, context, result2);
+      span?.fail(result2.error);
+      return result2;
+    }
+    if (!server || !server.manifest) {
+      const result2 = {
+        success: false,
+        error: "Tool server is not connected with a manifest; suggestion: run `pnpm tool:doctor`.",
+        duration: Date.now() - start
+      };
+      await this.#recordCall(toolName, shortName, serverId, context, result2);
+      span?.fail(result2.error);
+      return result2;
+    }
+    const consentRequest = {
+      tenantId: context.tenantId,
+      serverId: server.id,
+      toolName: shortName,
+      scopes: server.manifest.scopes,
+      ...context.userId !== void 0 && { userId: context.userId }
+    };
+    const hasConsent = await this.#consent.hasConsent(consentRequest);
+    if (!hasConsent) {
+      const result2 = {
+        success: false,
+        error: `Missing per-tool consent for ${server.id}:${shortName}; suggestion: grant scopes ${server.manifest.scopes.join(", ")}.`,
+        duration: Date.now() - start
+      };
+      await this.#recordCall(toolName, shortName, server.id, context, result2);
+      span?.fail(result2.error);
+      return result2;
+    }
+    const result = await this.#client.executeTool(toolName, args, context);
+    await this.#recordCall(toolName, shortName, server.id, context, result);
+    if (result.success) span?.end({ toolName });
+    else span?.fail(result.error);
+    return result;
+  }
+  listTools(context) {
+    return this.#client.listTools(context);
+  }
+  inspect(serverId) {
+    const server = this.#registry.getServer(serverId);
+    if (!server) {
+      throw new CapabilityError("tool-protocol", "MCP server not found", {
+        suggestion: "Run `pnpm tool:doctor` to list connected servers.",
+        metadata: { serverId },
+        statusCode: 404
+      });
+    }
+    void appendToolDebug({ type: "inspect", serverId, ok: true });
+    return server;
+  }
+  async doctor() {
+    const servers = this.#registry.getAllServers().map((server) => ({
+      id: server.id,
+      name: server.name,
+      transport: server.transport,
+      tools: server.tools.length,
+      ...server.manifest !== void 0 && { manifest: server.manifest }
+    }));
+    return {
+      ok: servers.length > 0,
+      servers,
+      ...servers.length === 0 && {
+        suggestion: "Connect an MCP server or register a local tool surface before running agents."
+      }
+    };
+  }
+  async debug(limit = 10) {
+    return readToolDebug(limit);
+  }
+  async close() {
+    await Promise.all(Array.from(this.#sdkClients.values()).map((client) => client.close()));
+    this.#sdkClients.clear();
+  }
+  async #connectSdkClient(options, transport, endpoint) {
+    const manifest = requireManifest(options.id, options.manifest);
+    const client = new Client({ name: "nebutra-tool-protocol", version: "0.1.0" });
+    await client.connect(transport);
+    const listed = await client.listTools();
+    const tools = listed.tools.map(
+      (tool) => ({
+        name: tool.name,
+        description: tool.description ?? tool.name,
+        parameters: {}
+      })
+    );
+    const handlers = Object.fromEntries(
+      tools.map((tool) => [
+        tool.name,
+        async (args) => {
+          return client.callTool({ name: tool.name, arguments: toJsonObject(args) });
+        }
+      ])
+    );
+    this.#sdkClients.set(options.id, client);
+    this.#registry.register({
+      id: options.id,
+      name: options.name ?? manifest.name,
+      description: options.description ?? `${manifest.name} MCP server`,
+      endpoint,
+      transport: endpoint.startsWith("stdio://") ? "stdio" : "http",
+      manifest,
+      tools,
+      handlers
+    });
+    await appendToolDebug({ type: "connect", serverId: options.id, ok: true });
+  }
+  async #recordCall(originalToolName, toolName, serverId, context, result) {
+    await appendToolDebug({
+      type: "tool_call",
+      requestId: context.requestId,
+      toolName,
+      ok: result.success,
+      durationMs: result.duration,
+      ...context.tenantId !== void 0 && { tenantId: context.tenantId },
+      ...serverId !== void 0 && { serverId },
+      ...result.error !== void 0 && { error: result.error }
+    });
+    if (result.success && context.tenantId && this.#eventLog) {
+      await this.#eventLog.commit({
+        traceId: context.requestId,
+        kind: "tool_call",
+        affected: [],
+        parent: null,
+        snapshot: {
+          [`tool/${serverId ?? "unknown"}/${toolName}.json`]: JSON.stringify({
+            toolName: originalToolName,
+            result: result.result
+          })
+        }
+      });
+    }
+  }
+};
+var toolConsentStore = new InMemoryToolConsentStore();
+var mcpHost = new McpHost({ consent: toolConsentStore });
+
+// src/middleware/mcpMiddleware.ts
+function createRateLimitMiddleware(options) {
+  const requests = /* @__PURE__ */ new Map();
+  return async (ctx, next) => {
+    const key = `${ctx.tenantId || "anon"}:${ctx.userId || "anon"}`;
+    const now = Date.now();
+    let record = requests.get(key);
+    if (!record || now > record.resetAt) {
+      record = { count: 0, resetAt: now + options.windowMs };
+      requests.set(key, record);
+    }
+    record.count++;
+    if (record.count > options.maxRequests) {
+      return {
+        success: false,
+        error: `MCP rate limit exceeded. Max ${options.maxRequests} requests per ${options.windowMs / 1e3}s`,
+        duration: 0
+      };
+    }
+    return next();
+  };
+}
+function createAuditMiddleware(options) {
+  return async (ctx, next) => {
+    const result = await next();
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId: ctx.requestId,
+      toolName: ctx.toolName,
+      arguments: ctx.arguments,
+      success: result.success,
+      duration: result.duration
+    };
+    if (ctx.tenantId) entry.tenantId = ctx.tenantId;
+    if (ctx.userId) entry.userId = ctx.userId;
+    if (result.error) entry.error = result.error;
+    Promise.resolve(options.onLog(entry)).catch(console.error);
+    return result;
+  };
+}
+function createAccessControlMiddleware(options) {
+  return async (ctx, next) => {
+    if (options.blockedTools?.includes(ctx.toolName)) {
+      return {
+        success: false,
+        error: `Tool ${ctx.toolName} is blocked`,
+        duration: 0
+      };
+    }
+    if (options.allowedTools && options.allowedTools.length > 0 && !options.allowedTools.includes(ctx.toolName)) {
+      return {
+        success: false,
+        error: `Tool ${ctx.toolName} is not in allowed list`,
+        duration: 0
+      };
+    }
+    return next();
+  };
+}
+function composeMCPMiddleware(middlewares) {
+  return async (ctx, finalNext) => {
+    let index = -1;
+    const dispatch = async (i) => {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+      const middleware = middlewares[i];
+      if (!middleware) {
+        return finalNext();
+      }
+      return middleware(ctx, () => dispatch(i + 1));
+    };
+    return dispatch(0);
+  };
+}
+
+// src/server/internalServers.ts
+var INTERNAL_SERVERS = [
+  // AI Service
+  {
+    id: "nebutra-ai",
+    name: "Nebutra AI Service",
+    description: "AI-powered text generation, embedding, and translation",
+    endpoint: process.env.AI_SERVICE_URL || "http://localhost:8001",
+    transport: "http",
+    tools: [
+      {
+        name: "generate_text",
+        description: "Generate text using LLM",
+        parameters: {
+          prompt: { type: "string", description: "Input prompt", required: true },
+          max_tokens: { type: "number", description: "Max tokens to generate", default: 1e3 },
+          temperature: { type: "number", description: "Sampling temperature", default: 0.7 }
+        },
+        returns: "Generated text"
+      },
+      {
+        name: "create_embedding",
+        description: "Create vector embedding for text",
+        parameters: {
+          text: { type: "string", description: "Text to embed", required: true },
+          model: {
+            type: "string",
+            description: "Embedding model",
+            default: "text-embedding-3-small"
+          }
+        },
+        returns: "Vector embedding array"
+      },
+      {
+        name: "translate",
+        description: "Translate text between languages",
+        parameters: {
+          text: { type: "string", description: "Text to translate", required: true },
+          source: { type: "string", description: "Source language code", default: "en" },
+          target: { type: "string", description: "Target language code", required: true }
+        },
+        returns: "Translated text"
+      }
+    ],
+    rateLimit: { maxRequests: 100, windowMs: 6e4 }
+  }
+];
+function registerInternalServers() {
+  for (const server of INTERNAL_SERVERS) {
+    serverRegistry.register(server);
+  }
+}
+function getInternalServerIds() {
+  return INTERNAL_SERVERS.map((s) => s.id);
+}
+
+// src/types.ts
+import { z } from "zod";
+var ToolParameterSchema = z.object({
+  type: z.enum(["string", "number", "boolean", "object", "array"]),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  default: z.any().optional()
+});
+var ToolDefinitionSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  parameters: z.record(z.string(), ToolParameterSchema).optional(),
+  returns: z.string().optional(),
+  allowedPlans: z.array(z.string()).optional(),
+  allowedTenants: z.array(z.string()).optional(),
+  requiredPermissions: z.array(z.string()).optional()
+});
+
+export {
+  MCPServerRegistry,
+  serverRegistry,
+  MCPClient,
+  mcpClient,
+  InMemoryToolConsentStore,
+  toolDebugPath,
+  appendToolDebug,
+  readToolDebug,
+  McpHost,
+  toolConsentStore,
+  mcpHost,
+  createRateLimitMiddleware,
+  createAuditMiddleware,
+  createAccessControlMiddleware,
+  composeMCPMiddleware,
+  INTERNAL_SERVERS,
+  registerInternalServers,
+  getInternalServerIds,
+  ToolParameterSchema,
+  ToolDefinitionSchema
+};