@nebutra/mcp 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -20,13 +20,14 @@
     "surface": "tool-protocol",
     "summary": "MCP server primitives (Model Context Protocol)"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client/index.ts",
-    "./server": "./src/server/index.ts",
-    "./middleware": "./src/middleware/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "bin": {
     "nebutra-mcp": "./dist/server/contextServer.js",
@@ -35,14 +36,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.3.6",
-    "@nebutra/capability-kit": "0.2.2",
+    "@nebutra/capability-kit": "0.2.4",
     "@nebutra/errors": "0.1.2",
-    "@nebutra/event-log": "0.1.2",
-    "@nebutra/ui": "0.2.2",
-    "@nebutra/trace-store": "0.1.2"
+    "@nebutra/event-log": "0.1.4",
+    "@nebutra/trace-store": "0.1.4",
+    "@nebutra/ui": "0.2.2"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
   },
   "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/mcp#readme",
   "repository": {
@@ -56,6 +59,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @nebutra/mcp@0.1.3 build /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/mcp
-> tsup
-
-CLI Building entry: src/cli.ts, src/index.ts, src/server/contextServer.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/mcp/tsup.config.ts
-CLI Target: node18
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js                883.00 B
-ESM dist/chunk-YMTQFRV2.js       5.25 KB
-ESM dist/cli.js                  1.47 KB
-ESM dist/chunk-25TNKUCR.js       28.60 KB
-ESM dist/server/contextServer.js 176.00 B
-ESM ⚡️ Build success in 24ms
-DTS Build start
-DTS ⚡️ Build success in 22181ms
-DTS dist/cli.d.ts                  13.00 B
-DTS dist/server/contextServer.d.ts 1.43 KB
-DTS dist/index.d.ts                12.19 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/mcp@0.1.2 test /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/mcp
-> vitest run
-
-
- RUN  v4.1.4 /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/mcp
-
- ✓ src/__tests__/registry-and-context.test.ts (4 tests) 68ms
-
- Test Files  1 passed (1)
-      Tests  4 passed (4)
-   Start at  09:40:36
-   Duration  1.41s (transform 252ms, setup 0ms, import 1.06s, tests 68ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/mcp@0.1.3 typecheck /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/mcp
-> tsc --noEmit
-

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,295 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-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";
-import { createUiAgentMcpServer } from "../server/uiAgentServer";
-
-const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../../..");
-
-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("Nebutra UI agent MCP tools", () => {
-  it("searches, validates, and returns migration hints from the generated UI contract", async () => {
-    const registry = new MCPServerRegistry();
-    registry.register(createUiAgentMcpServer());
-    const client = new MCPClient(registry);
-    const context = { requestId: "ui_1" };
-
-    expect(client.listTools(context).map((tool) => tool.name)).toEqual(
-      expect.arrayContaining([
-        "nebutra_ui_search_components",
-        "nebutra_ui_get_component",
-        "nebutra_ui_validate_component",
-        "nebutra_ui_get_migration_hints",
-      ]),
-    );
-
-    await expect(
-      client.executeTool(
-        "nebutra_ui_search_components",
-        { query: "button", limit: 1, root: repoRoot },
-        context,
-      ),
-    ).resolves.toMatchObject({
-      success: true,
-      result: {
-        items: [expect.objectContaining({ name: "button" })],
-      },
-    });
-
-    await expect(
-      client.executeTool(
-        "nebutra_ui_validate_component",
-        { name: "button", root: repoRoot },
-        context,
-      ),
-    ).resolves.toMatchObject({
-      success: true,
-      result: { name: "button", valid: true },
-    });
-
-    await expect(
-      client.executeTool(
-        "nebutra_ui_get_migration_hints",
-        { name: "button", root: repoRoot },
-        context,
-      ),
-    ).resolves.toMatchObject({
-      success: true,
-      result: {
-        component: "button",
-        dryRun: true,
-        hints: expect.arrayContaining([expect.stringContaining("breaking")]),
-      },
-    });
-  });
-});
-
-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";