@nebutra/mcp 0.1.2 → 0.1.4

package/AGENTS.md

@@ -1,62 +0,0 @@
-# AGENTS.md — packages/mcp
-
-Execution contract for Nebutra's Model Context Protocol package.
-
-## Scope
-
-Applies to everything under `packages/ai/mcp/`.
-
-This package owns checked-in MCP request and server types, the client runtime,
-middleware composition, in-process server registry, and the internal-server
-catalog exposed through MCP. It is an integration boundary and is still `wip`,
-not a production-complete tool platform.
-
-## Source Of Truth
-
-- Public package surface and subpath exports: `package.json`, `src/index.ts`
-- Canonical MCP types, tool definitions, request/response shapes, and server
-  config contract: `src/types.ts`
-- Client runtime and shared singleton: `src/client/mcpClient.ts`,
-  `src/client/index.ts`
-- Middleware composition, access control, audit, and rate-limit behavior:
-  `src/middleware/mcpMiddleware.ts`, `src/middleware/index.ts`
-- Server registry and registration semantics:
-  `src/registry/serverRegistry.ts`, `src/registry/index.ts`
-- Checked-in internal server catalog and registration entrypoint:
-  `src/server/internalServers.ts`, `src/server/index.ts`
-- Context server runtime entrypoint: `src/server/contextServer.ts`
-
-Treat `README.md` as descriptive only. If package behavior and docs disagree,
-update the source files above instead of preserving stale examples.
-
-## Contract Boundaries
-
-- Keep `package.json` exports, `src/index.ts`, and the `bin` contract aligned.
-  Public changes here affect client, middleware, and server consumers at once.
-- Treat `src/types.ts` as the canonical contract for tool definitions, request
-  envelopes, execution results, and server registration. Tightening those
-  shapes is a compatibility change.
-- Preserve the split between outbound client runtime, middleware pipeline, and
-  registry/server concerns. Client transport logic belongs in `src/client/`,
-  middleware semantics in `src/middleware/`, and checked-in server catalogs in
-  `src/server/` plus `src/registry/`.
-- Keep internal server declarations centralized in `src/server/internalServers.ts`.
-  Do not scatter internal MCP server metadata through apps or docs.
-- Respect the package's current `wip` status. The context server binary and
-  plan-based access control are not complete; do not document or code against
-  stronger production guarantees than the package actually provides.
-
-## Generated And Derived Files
-
-- `dist/` is derived build output from `tsup`.
-- The prepared `dist/server/contextServer.js` binary artifact is generated and
-  may be a placeholder stub before a full build.
-- Do not hand-edit emitted build output or generated CLI artifacts. Update the
-  source files above and rebuild instead.
-
-## Validation
-
-- Type or middleware/registry/client contract changes:
-  `pnpm --filter @nebutra/mcp typecheck`
-- Server entrypoint, subpath export, or bin changes:
-  `pnpm --filter @nebutra/mcp build`

package/bin/nebutra-mcp.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-import { startContextServer } from "../src/server/contextServer.js";
-
-// Starts the stdio MCP server for Cursor / Windsurf.
-startContextServer();

package/examples/doctor.ts

@@ -1,14 +0,0 @@
-import { McpHost } from "../src/index";
-
-const host = new McpHost();
-
-host.connectLocal({
-  id: "read-only",
-  name: "Read Only",
-  description: "Read-only example tools",
-  manifest: { name: "read-only", version: "1.0.0", scopes: ["project:read"] },
-  tools: [{ name: "ping", description: "Return pong" }],
-  handlers: { ping: async () => "pong" },
-});
-
-process.stdout.write(`${JSON.stringify(await host.doctor(), null, 2)}\n`);

package/examples/local-consent.ts

@@ -1,30 +0,0 @@
-import { InMemoryToolConsentStore, McpHost } from "../src/index";
-
-const consent = new InMemoryToolConsentStore();
-const host = new McpHost({ consent });
-
-host.connectLocal({
-  id: "notes",
-  name: "Notes",
-  description: "Tenant-scoped note tools",
-  manifest: { name: "notes", version: "1.0.0", scopes: ["notes:write"] },
-  tools: [{ name: "create_note", description: "Create a note" }],
-  handlers: {
-    create_note: async (args) => ({ id: "note_1", title: args.title }),
-  },
-});
-
-await consent.grant({
-  tenantId: "demo",
-  serverId: "notes",
-  toolName: "create_note",
-  scopes: ["notes:write"],
-});
-
-const result = await host.callTool(
-  "notes:create_note",
-  { title: "Layer 1" },
-  { requestId: "example_1", tenantId: "demo" },
-);
-
-process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/examples/read-debug.ts

@@ -1,5 +0,0 @@
-import { readToolDebug } from "../src/index";
-
-const entries = await readToolDebug(5);
-
-process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);

package/src/__tests__/registry-and-context.test.ts

@@ -1,234 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { MCPClient } from "../client/mcpClient";
-import { InMemoryToolConsentStore } from "../consent";
-import { readToolDebug } from "../debug";
-import { McpHost } from "../host";
-import { MCPServerRegistry } from "../registry/serverRegistry";
-import { createContextServerHandlers } from "../server/contextServer";
-
-describe("tool protocol host", () => {
-  it("requires manifest and per-tool consent before executing a connected server", async () => {
-    const consent = new InMemoryToolConsentStore();
-    const host = new McpHost({ consent });
-    const traces: string[] = [];
-
-    expect(() =>
-      host.connectLocal({
-        id: "unsafe",
-        name: "Unsafe",
-        description: "Missing manifest",
-        tools: [],
-        handlers: {},
-      }),
-    ).toThrow(/manifest/i);
-
-    host.connectLocal({
-      id: "notes",
-      name: "Notes",
-      description: "Tenant-scoped notes tools",
-      manifest: {
-        name: "notes",
-        version: "1.0.0",
-        scopes: ["notes:write"],
-      },
-      tools: [
-        {
-          name: "create_note",
-          description: "Create a note",
-          parameters: {},
-        },
-      ],
-      handlers: {
-        create_note: async (args, context) => {
-          traces.push(`${context.tenantId}:${args.title}`);
-          return { id: "note_1" };
-        },
-      },
-    });
-
-    await expect(
-      host.callTool("notes:create_note", { title: "Layer 1" }, { requestId: "r1" }),
-    ).resolves.toMatchObject({
-      success: false,
-      error: expect.stringContaining("tenant"),
-    });
-
-    const context = { requestId: "r2", tenantId: "tenant_a", userId: "user_1" };
-    await expect(
-      host.callTool("notes:create_note", { title: "Layer 1" }, context),
-    ).resolves.toMatchObject({
-      success: false,
-      error: expect.stringContaining("consent"),
-    });
-
-    await consent.grant({
-      tenantId: "tenant_a",
-      userId: "user_1",
-      serverId: "notes",
-      toolName: "create_note",
-      scopes: ["notes:write"],
-    });
-
-    await expect(
-      host.callTool("notes:create_note", { title: "Layer 1" }, context),
-    ).resolves.toMatchObject({
-      success: true,
-      result: { id: "note_1" },
-    });
-    expect(traces).toEqual(["tenant_a:Layer 1"]);
-  });
-
-  it("writes protocol debug entries for inspected calls", async () => {
-    const consent = new InMemoryToolConsentStore();
-    const host = new McpHost({ consent });
-    host.connectLocal({
-      id: "echo",
-      name: "Echo",
-      description: "Echo tools",
-      manifest: { name: "echo", version: "1.0.0", scopes: ["echo:run"] },
-      tools: [{ name: "say", description: "Say a value" }],
-      handlers: {
-        say: async (args) => args,
-      },
-    });
-    await consent.grant({
-      tenantId: "tenant_b",
-      serverId: "echo",
-      toolName: "say",
-      scopes: ["echo:run"],
-    });
-
-    await host.callTool("echo:say", { text: "ok" }, { requestId: "r3", tenantId: "tenant_b" });
-
-    await expect(readToolDebug(1)).resolves.toEqual([
-      expect.objectContaining({ type: "tool_call", serverId: "echo", toolName: "say", ok: true }),
-    ]);
-  });
-});
-
-describe("MCP tool registry access control", () => {
-  it("executes registered local tools only when tenant and plan policies pass", async () => {
-    const registry = new MCPServerRegistry();
-    registry.register({
-      id: "tenant-tools",
-      name: "Tenant tools",
-      description: "Tenant-scoped local tools",
-      endpoint: "local://tenant-tools",
-      transport: "local",
-      allowedTenants: ["tenant_allowed"],
-      tools: [
-        {
-          name: "summarize_context",
-          description: "Summarize tenant context",
-          parameters: {},
-        },
-        {
-          name: "sync_plan_data",
-          description: "Sync plan-gated data",
-          parameters: {},
-          allowedPlans: ["PRO", "ENTERPRISE"],
-        },
-      ],
-      handlers: {
-        summarize_context: async (args, context) => ({
-          args,
-          tenantId: context.tenantId,
-          plan: context.plan,
-        }),
-        sync_plan_data: async () => ({ synced: true }),
-      },
-    });
-
-    const client = new MCPClient(registry);
-    const freeContext = {
-      requestId: "req_1",
-      tenantId: "tenant_allowed",
-      plan: "FREE",
-    };
-
-    await expect(
-      client.executeTool("summarize_context", { topic: "billing" }, freeContext),
-    ).resolves.toMatchObject({
-      success: true,
-      result: { args: { topic: "billing" }, tenantId: "tenant_allowed", plan: "FREE" },
-    });
-
-    expect(client.listTools(freeContext).map((tool) => tool.name)).toEqual(["summarize_context"]);
-
-    await expect(client.executeTool("sync_plan_data", {}, freeContext)).resolves.toMatchObject({
-      success: false,
-      error: "Access denied to tool: sync_plan_data",
-    });
-
-    await expect(
-      client.executeTool(
-        "sync_plan_data",
-        {},
-        { requestId: "req_2", tenantId: "tenant_allowed", plan: "PRO" },
-      ),
-    ).resolves.toMatchObject({
-      success: true,
-      result: { synced: true },
-    });
-
-    await expect(
-      client.executeTool(
-        "summarize_context",
-        {},
-        { requestId: "req_3", tenantId: "tenant_blocked", plan: "ENTERPRISE" },
-      ),
-    ).resolves.toMatchObject({
-      success: false,
-      error: "Access denied to tool: summarize_context",
-    });
-  });
-});
-
-describe("context server handlers", () => {
-  const tempRoots: string[] = [];
-
-  afterEach(() => {
-    for (const root of tempRoots.splice(0)) {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
-    fs.rmSync(path.join(process.cwd(), ".nebutra"), { recursive: true, force: true });
-  });
-
-  it("lists project resources and returns non-placeholder project structure", async () => {
-    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nebutra-mcp-"));
-    tempRoots.push(projectRoot);
-    fs.mkdirSync(path.join(projectRoot, "apps", "web", "src", "app", "dashboard"), {
-      recursive: true,
-    });
-    fs.mkdirSync(path.join(projectRoot, "packages", "platform", "db", "prisma"), {
-      recursive: true,
-    });
-    fs.writeFileSync(path.join(projectRoot, "nebutra.config.json"), '{"features":["mcp"]}');
-    fs.writeFileSync(
-      path.join(projectRoot, "packages", "platform", "db", "prisma", "schema.prisma"),
-      "model User { id String @id }",
-    );
-
-    const handlers = createContextServerHandlers(projectRoot);
-    const resources = await handlers.listResources();
-    expect(resources.resources.map((resource) => resource.uri)).toContain(
-      "file:///nebutra.config.json",
-    );
-
-    const structure = await handlers.callTool({
-      name: "get_project_structure",
-      arguments: {},
-    });
-    expect(structure.content[0]?.text).toContain("apps/web/src/app/dashboard");
-    expect(structure.content[0]?.text).not.toContain("Apps dir not found");
-
-    await expect(
-      handlers.readResource({ uri: "file:///prisma/schema.prisma" }),
-    ).resolves.toMatchObject({
-      contents: [{ text: "model User { id String @id }" }],
-    });
-  });
-});

package/src/cli.ts

@@ -1,47 +0,0 @@
-import { McpHost, readToolDebug } from "./index";
-import { createContextServerHandlers } from "./server/contextServer";
-
-const command = process.argv[2] ?? "doctor";
-const host = new McpHost();
-const contextHandlers = createContextServerHandlers(process.cwd());
-
-host.connectLocal({
-  id: "nebutra-context",
-  name: "Nebutra Context",
-  description: "Read-only project context tools",
-  manifest: {
-    name: "nebutra-context",
-    version: "1.0.0",
-    scopes: ["project:read"],
-  },
-  tools: [
-    {
-      name: "get_project_structure",
-      description: "Returns a bounded app/package routing tree for the current project.",
-      parameters: {},
-    },
-  ],
-  handlers: {
-    get_project_structure: async () => contextHandlers.callTool({ name: "get_project_structure" }),
-  },
-});
-
-if (command === "doctor") {
-  process.stdout.write(
-    `${JSON.stringify({ capability: "tool-protocol", ...(await host.doctor()) }, null, 2)}\n`,
-  );
-} else if (command === "debug") {
-  const id = process.argv[3];
-  const entries = await readToolDebug(id ? 50 : 10);
-  process.stdout.write(
-    `${JSON.stringify({ capability: "tool-protocol", id, entries }, null, 2)}\n`,
-  );
-} else if (command === "inspect") {
-  const serverId = process.argv[3] ?? "nebutra-context";
-  process.stdout.write(
-    `${JSON.stringify({ capability: "tool-protocol", server: host.inspect(serverId) }, null, 2)}\n`,
-  );
-} else {
-  process.stderr.write(`Unknown tool-protocol command: ${command}\n`);
-  process.exitCode = 1;
-}

package/src/client/index.ts

@@ -1 +0,0 @@
-export { MCPClient, mcpClient } from "./mcpClient";

package/src/client/mcpClient.ts

@@ -1,193 +0,0 @@
-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;
-
-  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
-   */
-  private async executeHttp(
-    server: MCPServerConfig,
-    toolName: string,
-    args: Record<string, unknown>,
-    requestId: string,
-  ): Promise<unknown> {
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-      "X-Request-ID": requestId,
-    };
-
-    // Add authentication if configured
-    if (server.authentication?.type === "bearer") {
-      // In production, get token from secure storage
-      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
-   */
-  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[]>;
-}