@nebutra/mcp 0.1.3 → 0.1.4

package/src/client/mcpClient.ts

@@ -1,206 +0,0 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { MCPServerRegistry } from "../registry/serverRegistry";
-import { serverRegistry } from "../registry/serverRegistry";
-import type { MCPContext, MCPServerConfig, ToolExecutionResult } from "../types";
-
-/**
- * MCP Client for executing tools across registered servers
- */
-export class MCPClient {
-  private requestCounter = 0;
-  /** One SDK client per HTTP server id, reused across calls. */
-  private readonly httpClients = new Map<string, Client>();
-
-  constructor(private readonly registry: MCPServerRegistry = serverRegistry) {}
-
-  /**
-   * Execute a tool by name
-   */
-  async executeTool(
-    toolName: string,
-    args: Record<string, unknown>,
-    context: MCPContext,
-  ): Promise<ToolExecutionResult> {
-    const startTime = Date.now();
-
-    // Find server for this tool
-    const server = this.registry.findServerByTool(toolName);
-    if (!server) {
-      return {
-        success: false,
-        error: `Tool not found: ${toolName}`,
-        duration: Date.now() - startTime,
-      };
-    }
-
-    // Check access
-    if (!this.registry.canAccessTool(toolName, context)) {
-      return {
-        success: false,
-        error: `Access denied to tool: ${toolName}`,
-        duration: Date.now() - startTime,
-      };
-    }
-
-    // Execute based on transport
-    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
-   */
-  private async executeOnServer(
-    server: MCPServerConfig,
-    toolName: string,
-    args: Record<string, unknown>,
-    context: MCPContext,
-  ): Promise<unknown> {
-    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, using the official MCP SDK's
-   * StreamableHTTPClientTransport + Client to perform the `tools/call`.
-   */
-  private async executeHttp(
-    server: MCPServerConfig,
-    toolName: string,
-    args: Record<string, unknown>,
-    requestId: string,
-  ): Promise<unknown> {
-    const client = await this.getHttpClient(server, requestId);
-    const shortName = toolName.startsWith(`${server.id}:`)
-      ? toolName.slice(server.id.length + 1)
-      : toolName;
-    // SDK throws an McpError on JSON-RPC errors and a StreamableHTTPError on
-    // non-2xx responses; both propagate to executeTool's try/catch wrapper.
-    return client.callTool({ name: shortName, arguments: args });
-  }
-
-  /**
-   * Lazily create and cache an SDK Client connected over StreamableHTTP for a
-   * given server. Authentication headers are derived from the same env vars
-   * the previous hand-written transport used.
-   */
-  private async getHttpClient(server: MCPServerConfig, requestId: string): Promise<Client> {
-    const cached = this.httpClients.get(server.id);
-    if (cached) return cached;
-
-    const headers: Record<string, string> = {
-      "X-Request-ID": requestId,
-    };
-
-    // Add authentication if configured (same env-var contract as before).
-    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 transport = new StreamableHTTPClientTransport(new URL(server.endpoint), {
-      requestInit: { headers },
-    });
-    const client = new Client({ name: "nebutra-mcp-client", version: "0.1.0" });
-    // Cast mirrors host.ts: the SDK's Transport type is incompatible with the
-    // repo's exactOptionalPropertyTypes (sessionId?: string).
-    await client.connect(transport as Parameters<Client["connect"]>[0]);
-    this.httpClients.set(server.id, client);
-    return client;
-  }
-
-  /**
-   * Close all cached SDK HTTP clients and clear the cache.
-   */
-  async close(): Promise<void> {
-    await Promise.all(Array.from(this.httpClients.values()).map((client) => client.close()));
-    this.httpClients.clear();
-  }
-
-  /**
-   * Execute via WebSocket transport
-   */
-  private async executeWebSocket(
-    _server: MCPServerConfig,
-    _toolName: string,
-    _args: Record<string, unknown>,
-    _requestId: string,
-  ): Promise<unknown> {
-    // WebSocket implementation would maintain persistent connections
-    // For now, throw not implemented
-    throw new Error("WebSocket transport not yet implemented");
-  }
-
-  private async executeLocal(
-    server: MCPServerConfig,
-    toolName: string,
-    args: Record<string, unknown>,
-    context: MCPContext,
-  ): Promise<unknown> {
-    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: MCPContext) {
-    return this.registry.getAccessibleTools(context);
-  }
-
-  /**
-   * Get tool definition
-   */
-  getTool(toolName: string, context: MCPContext) {
-    const server = this.registry.findServerByTool(toolName);
-    if (!server) return undefined;
-
-    if (!this.registry.canAccessTool(toolName, context)) {
-      return undefined;
-    }
-
-    return server.tools.find((t) => t.name === toolName || `${server.id}:${t.name}` === toolName);
-  }
-}
-
-// Global client instance
-export const mcpClient = new MCPClient();

package/src/consent.ts

@@ -1,46 +0,0 @@
-export interface ToolConsentGrant {
-  readonly tenantId: string;
-  readonly userId?: string;
-  readonly serverId: string;
-  readonly toolName: string;
-  readonly scopes: readonly string[];
-}
-
-export interface ToolConsentStore {
-  grant(grant: ToolConsentGrant): Promise<void>;
-  hasConsent(grant: ToolConsentGrant): Promise<boolean>;
-  list(tenantId?: string): Promise<ToolConsentGrant[]>;
-}
-
-function consentKey(grant: Omit<ToolConsentGrant, "scopes">): string {
-  return [grant.tenantId, grant.userId ?? "*", grant.serverId, grant.toolName].join(":");
-}
-
-export class InMemoryToolConsentStore implements ToolConsentStore {
-  readonly #grants = new Map<string, ToolConsentGrant>();
-
-  async grant(grant: ToolConsentGrant): Promise<void> {
-    this.#grants.set(consentKey(grant), { ...grant, scopes: [...grant.scopes] });
-  }
-
-  async hasConsent(grant: ToolConsentGrant): Promise<boolean> {
-    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?: string): Promise<ToolConsentGrant[]> {
-    return Array.from(this.#grants.values()).filter(
-      (grant) => tenantId === undefined || grant.tenantId === tenantId,
-    );
-  }
-}

package/src/debug.ts

@@ -1,32 +0,0 @@
-import {
-  appendCapabilityDebug,
-  capabilityDebugPath,
-  readCapabilityDebug,
-} from "@nebutra/capability-kit/debug";
-
-export interface ToolDebugEntry {
-  readonly at: string;
-  readonly type: "tool_call" | "connect" | "inspect";
-  readonly requestId?: string;
-  readonly tenantId?: string;
-  readonly serverId?: string;
-  readonly toolName?: string;
-  readonly ok: boolean;
-  readonly durationMs?: number;
-  readonly error?: string;
-  readonly suggestion?: string;
-}
-
-export function toolDebugPath(): string {
-  return capabilityDebugPath("tool-protocol");
-}
-
-export async function appendToolDebug(
-  entry: Omit<ToolDebugEntry, "at"> & { at?: string },
-): Promise<void> {
-  await appendCapabilityDebug("tool-protocol", entry);
-}
-
-export async function readToolDebug(limit = 10): Promise<ToolDebugEntry[]> {
-  return readCapabilityDebug("tool-protocol", { limit }) as Promise<ToolDebugEntry[]>;
-}

package/src/host.ts

@@ -1,314 +0,0 @@
-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";
-import type { EventLog } from "@nebutra/event-log";
-import type { TraceStore } from "@nebutra/trace-store";
-import { MCPClient } from "./client/mcpClient";
-import { InMemoryToolConsentStore, type ToolConsentStore } from "./consent";
-import { appendToolDebug, readToolDebug } from "./debug";
-import { MCPServerRegistry } from "./registry/serverRegistry";
-import type {
-  MCPContext,
-  MCPServerConfig,
-  MCPServerManifest,
-  MCPToolHandler,
-  ToolDefinition,
-  ToolExecutionResult,
-} from "./types";
-
-export interface McpHostOptions {
-  readonly registry?: MCPServerRegistry;
-  readonly consent?: ToolConsentStore;
-  readonly traceStore?: TraceStore;
-  readonly eventLog?: EventLog;
-}
-
-export interface LocalMcpServerConfig {
-  readonly id: string;
-  readonly name: string;
-  readonly description: string;
-  readonly manifest?: MCPServerManifest;
-  readonly tools: readonly ToolDefinition[];
-  readonly handlers: Record<string, MCPToolHandler>;
-  readonly allowedPlans?: readonly string[];
-  readonly allowedTenants?: readonly string[];
-}
-
-export interface RemoteMcpConnectOptions {
-  readonly id: string;
-  readonly name?: string;
-  readonly description?: string;
-  readonly manifest: MCPServerManifest;
-  readonly headers?: Record<string, string>;
-}
-
-function shortToolName(serverId: string, toolName: string): string {
-  return toolName.startsWith(`${serverId}:`) ? toolName.slice(serverId.length + 1) : toolName;
-}
-
-function requireManifest(
-  serverId: string,
-  manifest: MCPServerManifest | undefined,
-): MCPServerManifest {
-  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: unknown): Record<string, unknown> {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : { value };
-}
-
-export class McpHost {
-  readonly #registry: MCPServerRegistry;
-  readonly #client: MCPClient;
-  readonly #consent: ToolConsentStore;
-  readonly #traceStore: TraceStore | undefined;
-  readonly #eventLog: EventLog | undefined;
-  readonly #sdkClients = new Map<string, Client>();
-
-  constructor(options: McpHostOptions = {}) {
-    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(): MCPServerRegistry {
-    return this.#registry;
-  }
-
-  connectLocal(config: LocalMcpServerConfig): void {
-    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 !== undefined && { allowedPlans: [...config.allowedPlans] }),
-      ...(config.allowedTenants !== undefined && { allowedTenants: [...config.allowedTenants] }),
-    });
-  }
-
-  async connectStdio(
-    command: string,
-    args: readonly string[],
-    options: RemoteMcpConnectOptions,
-  ): Promise<void> {
-    const transport = new StdioClientTransport({ command, args: [...args] });
-    await this.#connectSdkClient(options, transport, `stdio://${command}`);
-  }
-
-  async connectStreamableHttp(endpoint: string, options: RemoteMcpConnectOptions): Promise<void> {
-    const transport = new StreamableHTTPClientTransport(
-      new URL(endpoint),
-      options.headers !== undefined ? { requestInit: { headers: options.headers } } : {},
-    );
-    await this.#connectSdkClient(options, transport, endpoint);
-  }
-
-  async callTool(
-    toolName: string,
-    args: Record<string, unknown>,
-    context: MCPContext,
-  ): Promise<ToolExecutionResult> {
-    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 result = {
-        success: false,
-        error: "Missing tenant context; suggestion: call tools with a tenantId.",
-        duration: Date.now() - start,
-      };
-      await this.#recordCall(toolName, shortName, serverId, context, result);
-      span?.fail(result.error);
-      return result;
-    }
-
-    if (!server || !server.manifest) {
-      const result = {
-        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, result);
-      span?.fail(result.error);
-      return result;
-    }
-
-    const consentRequest = {
-      tenantId: context.tenantId,
-      serverId: server.id,
-      toolName: shortName,
-      scopes: server.manifest.scopes,
-      ...(context.userId !== undefined && { userId: context.userId }),
-    };
-    const hasConsent = await this.#consent.hasConsent(consentRequest);
-
-    if (!hasConsent) {
-      const result = {
-        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, result);
-      span?.fail(result.error);
-      return result;
-    }
-
-    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: MCPContext): Array<ToolDefinition & { serverId: string }> {
-    return this.#client.listTools(context);
-  }
-
-  inspect(serverId: string): MCPServerConfig {
-    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(): Promise<{
-    ok: boolean;
-    servers: Array<{
-      id: string;
-      name: string;
-      transport: MCPServerConfig["transport"];
-      tools: number;
-      manifest?: MCPServerManifest;
-    }>;
-    suggestion?: string;
-  }> {
-    const servers = this.#registry.getAllServers().map((server) => ({
-      id: server.id,
-      name: server.name,
-      transport: server.transport,
-      tools: server.tools.length,
-      ...(server.manifest !== undefined && { 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(): Promise<void> {
-    await Promise.all(Array.from(this.#sdkClients.values()).map((client) => client.close()));
-    this.#sdkClients.clear();
-  }
-
-  async #connectSdkClient(
-    options: RemoteMcpConnectOptions,
-    transport: unknown,
-    endpoint: string,
-  ): Promise<void> {
-    const manifest = requireManifest(options.id, options.manifest);
-    const client = new Client({ name: "nebutra-tool-protocol", version: "0.1.0" });
-    await client.connect(transport as Parameters<Client["connect"]>[0]);
-    const listed = await client.listTools();
-    const tools = listed.tools.map(
-      (tool) =>
-        ({
-          name: tool.name,
-          description: tool.description ?? tool.name,
-          parameters: {},
-        }) satisfies ToolDefinition,
-    );
-    const handlers = Object.fromEntries(
-      tools.map((tool) => [
-        tool.name,
-        async (args: Record<string, unknown>) => {
-          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: string,
-    toolName: string,
-    serverId: string | undefined,
-    context: MCPContext,
-    result: ToolExecutionResult,
-  ): Promise<void> {
-    await appendToolDebug({
-      type: "tool_call",
-      requestId: context.requestId,
-      toolName,
-      ok: result.success,
-      durationMs: result.duration,
-      ...(context.tenantId !== undefined && { tenantId: context.tenantId }),
-      ...(serverId !== undefined && { serverId }),
-      ...(result.error !== undefined && { 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,
-          }),
-        },
-      });
-    }
-  }
-}
-
-export const toolConsentStore = new InMemoryToolConsentStore();
-export const mcpHost = new McpHost({ consent: toolConsentStore });

package/src/index.ts

@@ -1,30 +0,0 @@
-// Types
-
-// Client
-export { MCPClient, mcpClient } from "./client/index";
-export {
-  InMemoryToolConsentStore,
-  type ToolConsentGrant,
-  type ToolConsentStore,
-} from "./consent";
-export { appendToolDebug, readToolDebug, type ToolDebugEntry, toolDebugPath } from "./debug";
-export { McpHost, mcpHost, toolConsentStore } from "./host";
-// Middleware
-export {
-  type AuditLogEntry,
-  composeMCPMiddleware,
-  createAccessControlMiddleware,
-  createAuditMiddleware,
-  createRateLimitMiddleware,
-  type MCPMiddleware,
-  type MCPMiddlewareContext,
-} from "./middleware/index";
-// Registry
-export { MCPServerRegistry, serverRegistry } from "./registry/index";
-// Server
-export {
-  getInternalServerIds,
-  INTERNAL_SERVERS,
-  registerInternalServers,
-} from "./server/index";
-export * from "./types";

package/src/middleware/index.ts

@@ -1,10 +0,0 @@
-export {
-  type AuditLogEntry,
-  composeMCPMiddleware,
-  createAccessControlMiddleware,
-  createAuditMiddleware,
-  createRateLimitMiddleware,
-  type MCPMiddleware,
-  type MCPMiddlewareContext,
-  type MCPMiddlewareNext,
-} from "./mcpMiddleware";