@nebutra/mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,123 +1,115 @@
 # @nebutra/mcp
 
-> **Status: WIP** — Not yet integrated into any production app. Do not import until this notice is removed.
+Model Context Protocol primitives for Nebutra agent and tool surfaces.
 
-Model Context Protocol (MCP) for AI agent tool calling.
+This package provides a registry, client, middleware, consent store, debug
+helpers, and internal-server registration seams around the official
+`@modelcontextprotocol/sdk` runtime.
 
-## Installation
+## Status: WIP
 
-```bash
-pnpm add @nebutra/mcp
-```
+Experimental public package. The package is published for reuse and contribution
+intake, but its package metadata still marks these production gaps explicitly:
 
-## Features
+- no production app integrations yet
+- no production MCP transports beyond HTTP/local seams
+- no durable remote tool discovery or app-level integration layer
 
-- **MCP Client** — Execute tools across registered servers
-- **Server Registry** — Manage internal and external MCP servers
-- **Middleware** — Rate limiting, audit logging, access control
-- **Plan-based Access** — Tool access based on subscription tier
+Use it for local tools, integration prototypes, and package development. Keep
+production deployments behind the application-level gateway and approval model.
 
-## Architecture
+## Installation
 
-```
-Agent → MCPClient → ServerRegistry → MCP Servers
-                  ↓
-            Middleware (rate-limit, audit, access-control)
+```bash
+pnpm add @nebutra/mcp
 ```
 
-## Usage
-
-### Initialize
-
-```typescript
-import { mcpClient, registerInternalServers } from "@nebutra/mcp";
-
-// Register built-in servers
-registerInternalServers();
-```
+## Exports
 
-### Execute Tools
+| Path | Description |
+| --- | --- |
+| `@nebutra/mcp` | Main registry, client, host, consent, debug, middleware, server, and type exports |
+| `@nebutra/mcp/client` | `MCPClient` and the shared `mcpClient` instance |
+| `@nebutra/mcp/server` | Internal server registration helpers |
+| `@nebutra/mcp/middleware` | Rate-limit, audit, access-control, and middleware composition helpers |
 
-```typescript
-const result = await mcpClient.executeTool(
-  "generate_text",
-  { prompt: "Write a product description" },
-  {
-    requestId: "req-123",
-    tenantId: "org_456",
-    plan: "PRO",
-  },
-);
-```
-
-### Available Tools
-
-| Tool              | Plan       | Description         |
-| ----------------- | ---------- | ------------------- |
-| `generate_text`   | FREE       | AI text generation  |
-| `translate`       | FREE       | AI translation      |
-| `embed_text`      | FREE       | Generate embeddings |
-| `recommend_items` | PRO        | Get recommendations |
-| `sync_products`   | PRO        | E-commerce sync     |
-| `mint_nft`        | ENTERPRISE | Web3 minting        |
-
-## Plan-based Access Control
-
-```typescript
-const plans = {
-  FREE: ["generate_text", "translate", "embed_text", "content_*"],
-  PRO: ["*_recommend_*", "*_ecommerce_*", ...FREE],
-  ENTERPRISE: ["*_web3_*", ...PRO],
-};
-```
+## Usage
 
-## Register Custom Server
+### Register a local server
 
-```typescript
-import { serverRegistry } from "@nebutra/mcp";
+```ts
+import { MCPClient, serverRegistry } from "@nebutra/mcp";
 
 serverRegistry.register({
-  name: "custom-tools",
-  url: "http://localhost:3001/mcp",
+  id: "workspace",
+  name: "Workspace tools",
+  description: "Local workspace utility tools",
+  endpoint: "local",
+  transport: "local",
   tools: [
     {
-      name: "custom_tool",
-      description: "My custom tool",
-      parameters: { type: "object", properties: {} },
+      name: "echo",
+      description: "Return the provided message",
+      parameters: {
+        message: { type: "string", required: true },
+      },
+      allowedPlans: ["PRO", "ENTERPRISE"],
     },
   ],
+  handlers: {
+    echo: (args) => ({ message: args.message }),
+  },
   allowedPlans: ["PRO", "ENTERPRISE"],
 });
+
+const client = new MCPClient(serverRegistry);
+const result = await client.executeTool(
+  "workspace:echo",
+  { message: "hello" },
+  {
+    requestId: "req_123",
+    tenantId: "org_123",
+    userId: "user_123",
+    plan: "PRO",
+  },
+);
 ```
 
-## Middleware
+### Register built-in servers
 
-### Rate Limiting
+```ts
+import { getInternalServerIds, registerInternalServers } from "@nebutra/mcp";
 
-```typescript
-// Configured per tool
-const limits = {
-  generate_text: { requests: 100, window: "1m" },
-  embed_text: { requests: 1000, window: "1h" },
-};
+registerInternalServers();
+const internalServerIds = getInternalServerIds();
 ```
 
-### Audit Logging
+### Compose middleware
+
+```ts
+import {
+  composeMCPMiddleware,
+  createAccessControlMiddleware,
+  createAuditMiddleware,
+  createRateLimitMiddleware,
+} from "@nebutra/mcp/middleware";
+
+const middleware = composeMCPMiddleware([
+  createRateLimitMiddleware({ maxRequests: 100, windowMs: 60_000 }),
+  createAccessControlMiddleware({ blockedTools: [] }),
+  createAuditMiddleware({ onLog: (entry) => auditSink.write(entry) }),
+]);
+```
 
-All tool executions are logged:
+## Runtime Notes
 
-```json
-{
-  "timestamp": "2024-01-15T10:30:00Z",
-  "tool": "generate_text",
-  "tenantId": "org_456",
-  "userId": "user_123",
-  "duration": 245,
-  "success": true
-}
-```
+- HTTP execution uses `StreamableHTTPClientTransport` from the official MCP SDK.
+- Local execution resolves registered handlers directly.
+- WebSocket execution is not implemented in this package.
+- `stdio` execution is rejected for browser/serverless contexts.
+- Tool access is checked at both server and tool level for plan, tenant, and
+  permission gates.
 
-## Related
+## License
 
-- [AI service](../../backends/python/ai/)
-- [API Gateway](../../backends/gateway/)
+MIT

package/dist/{chunk-ORGYGQJV.js → chunk-25TNKUCR.js}

@@ -1,3 +1,7 @@
+// src/client/mcpClient.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
 // src/registry/serverRegistry.ts
 var MCPServerRegistry = class {
   servers = /* @__PURE__ */ new Map();
@@ -134,7 +138,10 @@ var MCPClient = class {
   constructor(registry = serverRegistry) {
     this.registry = registry;
   }
+  registry;
   requestCounter = 0;
+  /** One SDK client per HTTP server id, reused across calls. */
+  httpClients = /* @__PURE__ */ new Map();
   /**
    * Execute a tool by name
    */
@@ -189,11 +196,23 @@ var MCPClient = class {
     }
   }
   /**
-   * Execute via HTTP transport
+   * Execute via HTTP transport, using the official MCP SDK's
+   * StreamableHTTPClientTransport + Client to perform the `tools/call`.
    */
   async executeHttp(server, toolName, args, requestId) {
+    const client = await this.getHttpClient(server, requestId);
+    const shortName = toolName.startsWith(`${server.id}:`) ? toolName.slice(server.id.length + 1) : toolName;
+    return client.callTool({ name: shortName, arguments: args });
+  }
+  /**
+   * Lazily create and cache an SDK Client connected over StreamableHTTP for a
+   * given server. Authentication headers are derived from the same env vars
+   * the previous hand-written transport used.
+   */
+  async getHttpClient(server, requestId) {
+    const cached = this.httpClients.get(server.id);
+    if (cached) return cached;
     const headers = {
-      "Content-Type": "application/json",
       "X-Request-ID": requestId
     };
     if (server.authentication?.type === "bearer") {
@@ -208,27 +227,20 @@ var MCPClient = class {
         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
-        }
-      })
+    const transport = new StreamableHTTPClientTransport(new URL(server.endpoint), {
+      requestInit: { headers }
     });
-    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;
+    const client = new Client({ name: "nebutra-mcp-client", version: "0.1.0" });
+    await client.connect(transport);
+    this.httpClients.set(server.id, client);
+    return client;
+  }
+  /**
+   * Close all cached SDK HTTP clients and clear the cache.
+   */
+  async close() {
+    await Promise.all(Array.from(this.httpClients.values()).map((client) => client.close()));
+    this.httpClients.clear();
   }
   /**
    * Execute via WebSocket transport
@@ -295,32 +307,25 @@ var InMemoryToolConsentStore = class {
 };
 
 // src/debug.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname, join } from "path";
+import {
+  appendCapabilityDebug,
+  capabilityDebugPath,
+  readCapabilityDebug
+} from "@nebutra/capability-kit/debug";
 function toolDebugPath() {
-  return join(process.cwd(), ".nebutra", "debug", "tool-protocol.jsonl");
+  return capabilityDebugPath("tool-protocol");
 }
 async function appendToolDebug(entry) {
-  const path = toolDebugPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
-`, {
-    flag: "a"
-  });
+  await appendCapabilityDebug("tool-protocol", entry);
 }
 async function readToolDebug(limit = 10) {
-  try {
-    const raw = await readFile(toolDebugPath(), "utf8");
-    return raw.trim().split("\n").filter(Boolean).slice(-limit).map((line) => JSON.parse(line));
-  } catch {
-    return [];
-  }
+  return readCapabilityDebug("tool-protocol", { limit });
 }
 
 // src/host.ts
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Client as Client2 } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport as StreamableHTTPClientTransport2 } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { CapabilityError } from "@nebutra/errors";
 function shortToolName(serverId, toolName) {
   return toolName.startsWith(`${serverId}:`) ? toolName.slice(serverId.length + 1) : toolName;
@@ -375,7 +380,7 @@ var McpHost = class {
     await this.#connectSdkClient(options, transport, `stdio://${command}`);
   }
   async connectStreamableHttp(endpoint, options) {
-    const transport = new StreamableHTTPClientTransport(
+    const transport = new StreamableHTTPClientTransport2(
       new URL(endpoint),
       options.headers !== void 0 ? { requestInit: { headers: options.headers } } : {}
     );
@@ -475,7 +480,7 @@ var McpHost = class {
   }
   async #connectSdkClient(options, transport, endpoint) {
     const manifest = requireManifest(options.id, options.manifest);
-    const client = new Client({ name: "nebutra-tool-protocol", version: "0.1.0" });
+    const client = new Client2({ name: "nebutra-tool-protocol", version: "0.1.0" });
     await client.connect(transport);
     const listed = await client.listTools();
     const tools = listed.tools.map(
@@ -613,8 +618,160 @@ function composeMCPMiddleware(middlewares) {
   };
 }
 
+// src/server/uiAgentServer.ts
+import {
+  loadAgentComponentContract,
+  loadAgentManifest,
+  searchAgentComponents,
+  validateAgentComponent
+} from "@nebutra/ui/agent";
+function readContractOptions(args) {
+  const options = {
+    root: typeof args.root === "string" ? args.root : process.cwd()
+  };
+  if (typeof args.manifestPath === "string") {
+    options.manifestPath = args.manifestPath;
+  }
+  return options;
+}
+function readName(args) {
+  const name = args.name;
+  if (typeof name !== "string" || name.trim().length === 0) {
+    throw new Error('Missing required component name. Pass a registry id such as "button".');
+  }
+  return name;
+}
+function validateAll(args) {
+  const options = readContractOptions(args);
+  const manifest = loadAgentManifest(options);
+  const results = manifest.components.map(
+    (component) => validateAgentComponent(loadAgentComponentContract(component.name, options))
+  );
+  const invalid = results.filter((result) => !result.valid).length;
+  return {
+    valid: invalid === 0,
+    total: results.length,
+    invalid,
+    results
+  };
+}
+function createUiAgentMcpServer() {
+  return {
+    id: "nebutra-ui-agent",
+    name: "Nebutra UI Agent Contract",
+    description: "Read-only tools for @nebutra/ui agent contracts, production evidence, and migration hints.",
+    endpoint: "local://nebutra-ui-agent",
+    transport: "local",
+    manifest: {
+      name: "nebutra-ui-agent",
+      version: "1.0.0",
+      scopes: ["ui:read"],
+      homepage: "https://ui.nebutra.com"
+    },
+    tools: [
+      {
+        name: "nebutra_ui_search_components",
+        description: "Search the Nebutra UI agent manifest by query, tag, status, or maturity.",
+        parameters: {
+          query: { type: "string", description: "Search text such as button, table, or chat" },
+          limit: { type: "number", description: "Maximum results to return", default: 20 },
+          offset: { type: "number", description: "Pagination offset", default: 0 },
+          tag: { type: "string", description: "Optional generated tag filter" },
+          status: { type: "string", description: "Optional status filter" },
+          maturity: { type: "string", description: "Optional maturity filter" },
+          root: { type: "string", description: "Optional Nebutra monorepo root override" },
+          manifestPath: {
+            type: "string",
+            description: "Optional agent-manifest.json path override"
+          }
+        },
+        returns: "Paginated component search results with stable component ids"
+      },
+      {
+        name: "nebutra_ui_get_component",
+        description: "Read one Nebutra UI component contract by registry id.",
+        parameters: {
+          name: { type: "string", description: "Component id, for example button", required: true },
+          root: { type: "string", description: "Optional Nebutra monorepo root override" },
+          manifestPath: {
+            type: "string",
+            description: "Optional agent-manifest.json path override"
+          }
+        },
+        returns: "Full component contract with imports, evidence, tokens, docs, and migration policy"
+      },
+      {
+        name: "nebutra_ui_validate_component",
+        description: "Validate production evidence for one component or the full UI contract.",
+        parameters: {
+          name: { type: "string", description: "Optional component id; omit to validate all" },
+          root: { type: "string", description: "Optional Nebutra monorepo root override" },
+          manifestPath: {
+            type: "string",
+            description: "Optional agent-manifest.json path override"
+          }
+        },
+        returns: "Validation result with errors and warnings"
+      },
+      {
+        name: "nebutra_ui_get_migration_hints",
+        description: "Read dry-run codemod and migration hints for one component.",
+        parameters: {
+          name: { type: "string", description: "Component id, for example button", required: true },
+          root: { type: "string", description: "Optional Nebutra monorepo root override" },
+          manifestPath: {
+            type: "string",
+            description: "Optional agent-manifest.json path override"
+          }
+        },
+        returns: "Migration hints and registered codemod ids"
+      }
+    ],
+    handlers: {
+      nebutra_ui_search_components: async (args) => {
+        const manifest = loadAgentManifest(readContractOptions(args));
+        const searchOptions = {
+          limit: typeof args.limit === "number" ? args.limit : 20,
+          offset: typeof args.offset === "number" ? args.offset : 0
+        };
+        if (typeof args.tag === "string") searchOptions.tag = args.tag;
+        if (typeof args.status === "string") searchOptions.status = args.status;
+        if (typeof args.maturity === "string") {
+          searchOptions.maturity = args.maturity;
+        }
+        return searchAgentComponents(
+          manifest,
+          typeof args.query === "string" ? args.query : "",
+          searchOptions
+        );
+      },
+      nebutra_ui_get_component: async (args) => loadAgentComponentContract(readName(args), readContractOptions(args)),
+      nebutra_ui_validate_component: async (args) => {
+        if (typeof args.name === "string" && args.name.trim().length > 0) {
+          return validateAgentComponent(
+            loadAgentComponentContract(args.name, readContractOptions(args))
+          );
+        }
+        return validateAll(args);
+      },
+      nebutra_ui_get_migration_hints: async (args) => {
+        const contract = loadAgentComponentContract(readName(args), readContractOptions(args));
+        return {
+          component: contract.name,
+          dryRun: true,
+          codemods: contract.migration.codemods,
+          hints: contract.migration.hints,
+          requiredForBreakingChanges: contract.migration.requiredForBreakingChanges
+        };
+      }
+    },
+    rateLimit: { maxRequests: 300, windowMs: 6e4 }
+  };
+}
+
 // src/server/internalServers.ts
 var INTERNAL_SERVERS = [
+  createUiAgentMcpServer(),
   // AI Service
   {
     id: "nebutra-ai",

package/dist/cli.js

@@ -1,7 +1,7 @@
 import {
   McpHost,
   readToolDebug
-} from "./chunk-ORGYGQJV.js";
+} from "./chunk-25TNKUCR.js";
 import {
   createContextServerHandlers
 } from "./chunk-YMTQFRV2.js";

package/dist/index.d.ts

@@ -170,6 +170,8 @@ declare const serverRegistry: MCPServerRegistry;
 declare class MCPClient {
     private readonly registry;
     private requestCounter;
+    /** One SDK client per HTTP server id, reused across calls. */
+    private readonly httpClients;
     constructor(registry?: MCPServerRegistry);
     /**
      * Execute a tool by name
@@ -180,9 +182,20 @@ declare class MCPClient {
      */
     private executeOnServer;
     /**
-     * Execute via HTTP transport
+     * Execute via HTTP transport, using the official MCP SDK's
+     * StreamableHTTPClientTransport + Client to perform the `tools/call`.
      */
     private executeHttp;
+    /**
+     * Lazily create and cache an SDK Client connected over StreamableHTTP for a
+     * given server. Authentication headers are derived from the same env vars
+     * the previous hand-written transport used.
+     */
+    private getHttpClient;
+    /**
+     * Close all cached SDK HTTP clients and clear the cache.
+     */
+    close(): Promise<void>;
     /**
      * Execute via WebSocket transport
      */

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   serverRegistry,
   toolConsentStore,
   toolDebugPath
-} from "./chunk-ORGYGQJV.js";
+} from "./chunk-25TNKUCR.js";
 export {
   INTERNAL_SERVERS,
   InMemoryToolConsentStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
     ],
     "featureId": "mcp",
     "category": "ai",
+    "surface": "tool-protocol",
     "summary": "MCP server primitives (Model Context Protocol)"
   },
   "main": "./src/index.ts",
@@ -32,11 +33,13 @@
     "nebutra-tool-protocol": "./dist/cli.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.3.6",
-    "@nebutra/errors": "0.1.0",
-    "@nebutra/event-log": "0.1.0",
-    "@nebutra/trace-store": "0.1.0"
+    "@nebutra/capability-kit": "0.2.2",
+    "@nebutra/errors": "0.1.2",
+    "@nebutra/event-log": "0.1.2",
+    "@nebutra/ui": "0.2.2",
+    "@nebutra/trace-store": "0.1.2"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

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

@@ -1,6 +1,7 @@
 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";
@@ -8,6 +9,9 @@ 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 () => {
@@ -187,6 +191,63 @@ describe("MCP tool registry access control", () => {
   });
 });
 
+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[] = [];