@nebutra/mcp 0.1.0 → 0.1.2

package/src/host.ts

@@ -0,0 +1,314 @@
+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

@@ -2,6 +2,13 @@
 
 // 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,

package/src/registry/serverRegistry.ts

@@ -106,6 +106,35 @@ export class MCPServerRegistry {
     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
    */
@@ -115,13 +144,21 @@ export class MCPServerRegistry {
     for (const server of this.servers.values()) {
       if (this.canAccess(server.id, context)) {
         for (const tool of server.tools) {
-          tools.push({ ...tool, serverId: server.id });
+          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

package/src/server/contextServer.ts

@@ -43,43 +43,74 @@ class NebutraContextServer {
   }
 
   private setupResourceHandlers() {
-    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-      resources: [
-        {
-          uri: "file:///nebutra.config.json",
-          name: "Nebutra Configuration",
-          mimeType: "application/json",
-          description:
-            "Global configurations for the Nebutra template including enabled features (auth, payments, i18n, db).",
-        },
-        {
-          uri: "file:///prisma/schema.prisma",
-          name: "Database Schema Overview",
-          mimeType: "text/plain",
-          description: "The core Prisma schema defining the database tables and relationships.",
-        },
-      ],
-    }));
+    const handlers = createContextServerHandlers(this.projectRoot);
+
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => handlers.listResources());
 
     this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const { uri } = request.params;
-
-      let filePath = "";
-      if (uri === "file:///nebutra.config.json") {
-        filePath = path.join(this.projectRoot, "nebutra.config.json");
-      } else if (uri === "file:///prisma/schema.prisma") {
-        filePath = path.join(this.projectRoot, "packages/platform/db/prisma/schema.prisma");
-      } else {
+      return handlers.readResource(request.params);
+    });
+  }
+
+  private setupToolHandlers() {
+    const handlers = createContextServerHandlers(this.projectRoot);
+
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => handlers.listTools());
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      return handlers.callTool(request.params);
+    });
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+}
+
+const RESOURCE_MAP = {
+  "file:///nebutra.config.json": {
+    relativePath: "nebutra.config.json",
+    name: "Nebutra Configuration",
+    mimeType: "application/json",
+    description:
+      "Global configurations for the Nebutra template including enabled features (auth, payments, i18n, db).",
+  },
+  "file:///prisma/schema.prisma": {
+    relativePath: "packages/platform/db/prisma/schema.prisma",
+    name: "Database Schema Overview",
+    mimeType: "text/plain",
+    description: "The core Prisma schema defining the database tables and relationships.",
+  },
+} as const;
+
+export function createContextServerHandlers(projectRoot: string) {
+  return {
+    async listResources() {
+      return {
+        resources: Object.entries(RESOURCE_MAP).map(([uri, resource]) => ({
+          uri,
+          name: resource.name,
+          mimeType: resource.mimeType,
+          description: resource.description,
+        })),
+      };
+    },
+
+    async readResource({ uri }: { uri: string }) {
+      const resource = RESOURCE_MAP[uri as keyof typeof RESOURCE_MAP];
+      if (!resource) {
         throw new Error(`Resource not found: ${uri}`);
       }
 
+      const filePath = path.join(projectRoot, resource.relativePath);
       try {
         const content = fs.readFileSync(filePath, "utf-8");
         return {
           contents: [
             {
               uri,
-              mimeType: uri.endsWith(".json") ? "application/json" : "text/plain",
+              mimeType: resource.mimeType,
               text: content,
             },
           ],
@@ -87,43 +118,85 @@ class NebutraContextServer {
       } catch {
         throw new Error(`Failed to read the requested resource file at ${filePath}`);
       }
-    });
-  }
+    },
 
-  private setupToolHandlers() {
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: [
-        {
-          name: "get_project_structure",
-          description: "Retrieves the core Next.js routing tree from the apps folder.",
-          inputSchema: {
-            type: "object",
-            properties: {},
-            required: [],
+    async listTools() {
+      return {
+        tools: [
+          {
+            name: "get_project_structure",
+            description: "Returns a bounded app/package routing tree for the current project.",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
           },
-        },
-      ],
-    }));
+        ],
+      };
+    },
 
-    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      if (request.params.name === "get_project_structure") {
-        try {
-          const appsDir = path.join(this.projectRoot, "apps");
-          if (!fs.existsSync(appsDir))
-            return { content: [{ type: "text", text: "Apps dir not found." }] };
-          const dirs = fs.readdirSync(appsDir);
-          return { content: [{ type: "text", text: `Apps: ${dirs.join(", ")}` }] };
-        } catch (error) {
-          return { content: [{ type: "text", text: `Error: ${error}` }], isError: true };
-        }
+    async callTool({ name }: { name: string; arguments?: Record<string, unknown> | undefined }) {
+      if (name !== "get_project_structure") {
+        throw new Error(`Unknown tool: ${name}`);
       }
-      throw new Error(`Unknown tool: ${request.params.name}`);
-    });
+
+      try {
+        return {
+          content: [
+            {
+              type: "text",
+              text: getProjectStructure(projectRoot),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  };
+}
+
+function getProjectStructure(projectRoot: string): string {
+  const roots = ["apps", "packages", "backends"].filter((segment) =>
+    fs.existsSync(path.join(projectRoot, segment)),
+  );
+  if (roots.length === 0) return "No Nebutra workspace roots found.";
+
+  const entries: string[] = [];
+  for (const root of roots) {
+    walkProjectTree(path.join(projectRoot, root), root, entries, 4);
   }
+  return entries.length > 0 ? entries.join("\n") : "No project entries found.";
+}
 
-  async run() {
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
+function walkProjectTree(
+  absoluteDir: string,
+  relativeDir: string,
+  entries: string[],
+  depthRemaining: number,
+): void {
+  if (depthRemaining < 0 || entries.length >= 200) return;
+
+  entries.push(relativeDir);
+
+  for (const dirent of fs.readdirSync(absoluteDir, { withFileTypes: true })) {
+    if (!dirent.isDirectory()) continue;
+    if (dirent.name === "node_modules" || dirent.name.startsWith(".")) continue;
+    walkProjectTree(
+      path.join(absoluteDir, dirent.name),
+      path.join(relativeDir, dirent.name),
+      entries,
+      depthRemaining - 1,
+    );
   }
 }
 

package/src/types.ts

@@ -16,6 +16,9 @@ export const ToolDefinitionSchema = z.object({
   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 type ToolParameter = z.infer<typeof ToolParameterSchema>;
@@ -74,6 +77,13 @@ export interface ToolExecutionResult {
   tokensUsed?: number;
 }
 
+export interface MCPServerManifest {
+  name: string;
+  version: string;
+  scopes: string[];
+  homepage?: string;
+}
+
 // ============================================
 // MCP Server Registration
 // ============================================
@@ -83,8 +93,10 @@ export interface MCPServerConfig {
   name: string;
   description: string;
   endpoint: string;
-  transport: "http" | "websocket" | "stdio";
+  transport: "http" | "websocket" | "stdio" | "local";
+  manifest?: MCPServerManifest;
   tools: ToolDefinition[];
+  handlers?: Record<string, MCPToolHandler>;
   authentication?: {
     type: "bearer" | "api-key" | "none";
     headerName?: string;
@@ -98,6 +110,11 @@ export interface MCPServerConfig {
   allowedTenants?: string[]; // specific tenant IDs
 }
 
+export type MCPToolHandler = (
+  args: Record<string, unknown>,
+  context: MCPContext,
+) => unknown | Promise<unknown>;
+
 // ============================================
 // Smithery Integration
 // ============================================

package/tsup.config.ts

@@ -1,11 +1,17 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-  entry: ["src/index.ts", "src/server/contextServer.ts"],
+  entry: ["src/index.ts", "src/cli.ts", "src/server/contextServer.ts"],
   format: ["esm"],
   dts: true,
   clean: true,
   target: "node18",
   outDir: "dist",
   minify: false,
+  external: [
+    "@modelcontextprotocol/sdk",
+    "@nebutra/errors",
+    "@nebutra/event-log",
+    "@nebutra/trace-store",
+  ],
 });