@nebutra/mcp 0.1.0 → 0.1.2

package/dist/server/contextServer.js

@@ -1 +1,9 @@
 #!/usr/bin/env node
+import {
+  createContextServerHandlers,
+  startContextServer
+} from "../chunk-YMTQFRV2.js";
+export {
+  createContextServerHandlers,
+  startContextServer
+};

package/examples/doctor.ts

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

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

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nebutra/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "wip",
@@ -12,11 +12,12 @@
     ],
     "gaps": [
       "No production app integrations",
-      "Context server binary is a placeholder stub",
-      "Tool registry + plan-based access control pending"
+      "No production MCP transports beyond HTTP/local seams",
+      "No durable remote tool discovery or app-level integrations"
     ],
     "featureId": "mcp",
     "category": "ai",
+    "surface": "tool-protocol",
     "summary": "MCP server primitives (Model Context Protocol)"
   },
   "main": "./src/index.ts",
@@ -28,11 +29,16 @@
     "./middleware": "./src/middleware/index.ts"
   },
   "bin": {
-    "nebutra-mcp": "./dist/server/contextServer.js"
+    "nebutra-mcp": "./dist/server/contextServer.js",
+    "nebutra-tool-protocol": "./dist/cli.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^4.3.6"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.3.6",
+    "@nebutra/capability-kit": "0.2.1",
+    "@nebutra/errors": "0.1.1",
+    "@nebutra/event-log": "0.1.1",
+    "@nebutra/trace-store": "0.1.1"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -52,6 +58,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }

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

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

@@ -0,0 +1,47 @@
+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/mcpClient.ts

@@ -1,3 +1,4 @@
+import type { MCPServerRegistry } from "../registry/serverRegistry";
 import { serverRegistry } from "../registry/serverRegistry";
 import type { MCPContext, MCPServerConfig, ToolExecutionResult } from "../types";
 
@@ -7,6 +8,8 @@ import type { MCPContext, MCPServerConfig, ToolExecutionResult } from "../types"
 export class MCPClient {
   private requestCounter = 0;
 
+  constructor(private readonly registry: MCPServerRegistry = serverRegistry) {}
+
   /**
    * Execute a tool by name
    */
@@ -18,7 +21,7 @@ export class MCPClient {
     const startTime = Date.now();
 
     // Find server for this tool
-    const server = serverRegistry.findServerByTool(toolName);
+    const server = this.registry.findServerByTool(toolName);
     if (!server) {
       return {
         success: false,
@@ -28,7 +31,7 @@ export class MCPClient {
     }
 
     // Check access
-    if (!serverRegistry.canAccess(server.id, context)) {
+    if (!this.registry.canAccessTool(toolName, context)) {
       return {
         success: false,
         error: `Access denied to tool: ${toolName}`,
@@ -69,6 +72,8 @@ export class MCPClient {
         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:
@@ -146,21 +151,37 @@ export class MCPClient {
     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 serverRegistry.getAccessibleTools(context);
+    return this.registry.getAccessibleTools(context);
   }
 
   /**
    * Get tool definition
    */
   getTool(toolName: string, context: MCPContext) {
-    const server = serverRegistry.findServerByTool(toolName);
+    const server = this.registry.findServerByTool(toolName);
     if (!server) return undefined;
 
-    if (!serverRegistry.canAccess(server.id, context)) {
+    if (!this.registry.canAccessTool(toolName, context)) {
       return undefined;
     }
 

package/src/consent.ts

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

@@ -0,0 +1,32 @@
+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[]>;
+}