@nebutra/mcp 0.1.2 → 0.1.4

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";

package/src/middleware/mcpMiddleware.ts

@@ -1,150 +0,0 @@
-import type { MCPContext, ToolExecutionResult } from "../types";
-
-/**
- * MCP Middleware for rate limiting, audit logging, and access control
- */
-
-export interface MCPMiddlewareContext extends MCPContext {
-  toolName: string;
-  arguments: Record<string, unknown>;
-}
-
-export type MCPMiddlewareNext = () => Promise<ToolExecutionResult>;
-
-export type MCPMiddleware = (
-  ctx: MCPMiddlewareContext,
-  next: MCPMiddlewareNext,
-) => Promise<ToolExecutionResult>;
-
-/**
- * Rate limiting middleware for MCP calls
- */
-export function createRateLimitMiddleware(options: {
-  maxRequests: number;
-  windowMs: number;
-}): MCPMiddleware {
-  const requests = new Map<string, { count: number; resetAt: number }>();
-
-  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 / 1000}s`,
-        duration: 0,
-      };
-    }
-
-    return next();
-  };
-}
-
-/**
- * Audit logging middleware
- */
-export function createAuditMiddleware(options: {
-  onLog: (entry: AuditLogEntry) => void | Promise<void>;
-}): MCPMiddleware {
-  return async (ctx, next) => {
-    const result = await next();
-
-    const entry: AuditLogEntry = {
-      timestamp: 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;
-
-    // Don't block on audit logging
-    Promise.resolve(options.onLog(entry)).catch(console.error);
-
-    return result;
-  };
-}
-
-export interface AuditLogEntry {
-  timestamp: string;
-  requestId: string;
-  tenantId?: string;
-  userId?: string;
-  toolName: string;
-  arguments: Record<string, unknown>;
-  success: boolean;
-  duration: number;
-  error?: string;
-}
-
-/**
- * Tool access control middleware
- */
-export function createAccessControlMiddleware(options: {
-  blockedTools?: string[];
-  allowedTools?: string[];
-}): MCPMiddleware {
-  return async (ctx, next) => {
-    // Check blocked list
-    if (options.blockedTools?.includes(ctx.toolName)) {
-      return {
-        success: false,
-        error: `Tool ${ctx.toolName} is blocked`,
-        duration: 0,
-      };
-    }
-
-    // Check allowed list (if specified)
-    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();
-  };
-}
-
-/**
- * Compose multiple middlewares
- */
-export function composeMCPMiddleware(middlewares: MCPMiddleware[]): MCPMiddleware {
-  return async (ctx, finalNext) => {
-    let index = -1;
-
-    const dispatch = async (i: number): Promise<ToolExecutionResult> => {
-      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);
-  };
-}

package/src/registry/index.ts

@@ -1 +0,0 @@
-export { MCPServerRegistry, serverRegistry } from "./serverRegistry";

package/src/registry/serverRegistry.ts

@@ -1,165 +0,0 @@
-import type { MCPContext, MCPServerConfig, ToolDefinition } from "../types";
-
-/**
- * Registry for MCP servers and their tools
- * Handles server registration, discovery, and access control
- */
-export class MCPServerRegistry {
-  private servers: Map<string, MCPServerConfig> = new Map();
-  private toolIndex: Map<string, string> = new Map(); // tool name -> server id
-
-  /**
-   * Register an MCP server
-   */
-  register(config: MCPServerConfig): void {
-    this.servers.set(config.id, config);
-
-    // Index tools for quick lookup
-    for (const tool of config.tools) {
-      const qualifiedName = `${config.id}:${tool.name}`;
-      this.toolIndex.set(qualifiedName, config.id);
-      // Also allow short name if unique
-      if (!this.toolIndex.has(tool.name)) {
-        this.toolIndex.set(tool.name, config.id);
-      }
-    }
-  }
-
-  /**
-   * Unregister an MCP server
-   */
-  unregister(serverId: string): boolean {
-    const server = this.servers.get(serverId);
-    if (!server) return false;
-
-    // Remove tool index entries
-    for (const tool of server.tools) {
-      const qualifiedName = `${serverId}:${tool.name}`;
-      this.toolIndex.delete(qualifiedName);
-      // Only remove short name if it points to this server
-      if (this.toolIndex.get(tool.name) === serverId) {
-        this.toolIndex.delete(tool.name);
-      }
-    }
-
-    this.servers.delete(serverId);
-    return true;
-  }
-
-  /**
-   * Get server by ID
-   */
-  getServer(serverId: string): MCPServerConfig | undefined {
-    return this.servers.get(serverId);
-  }
-
-  /**
-   * Find server by tool name
-   */
-  findServerByTool(toolName: string): MCPServerConfig | undefined {
-    const serverId = this.toolIndex.get(toolName);
-    if (!serverId) return undefined;
-    return this.servers.get(serverId);
-  }
-
-  /**
-   * Get all registered servers
-   */
-  getAllServers(): MCPServerConfig[] {
-    return Array.from(this.servers.values());
-  }
-
-  /**
-   * Get all available tools
-   */
-  getAllTools(): Array<ToolDefinition & { serverId: string }> {
-    const tools: Array<ToolDefinition & { serverId: string }> = [];
-    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: string, context: MCPContext): boolean {
-    const server = this.servers.get(serverId);
-    if (!server) return false;
-
-    // Check plan restrictions
-    if (server.allowedPlans && server.allowedPlans.length > 0) {
-      if (!context.plan || !server.allowedPlans.includes(context.plan)) {
-        return false;
-      }
-    }
-
-    // Check tenant restrictions
-    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: string, context: MCPContext): boolean {
-    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: MCPContext): Array<ToolDefinition & { serverId: string }> {
-    const tools: Array<ToolDefinition & { serverId: string }> = [];
-
-    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;
-  }
-
-  private findTool(server: MCPServerConfig, toolName: string): ToolDefinition | undefined {
-    return server.tools.find(
-      (tool) => tool.name === toolName || `${server.id}:${tool.name}` === toolName,
-    );
-  }
-}
-
-// Global registry instance
-export const serverRegistry = new MCPServerRegistry();