@nebutra/mcp 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @nebutra/mcp
+
+> **Status: WIP** — Not yet integrated into any production app. Do not import until this notice is removed.
+
+Model Context Protocol (MCP) for AI agent tool calling.
+
+## Installation
+
+```bash
+pnpm add @nebutra/mcp
+```
+
+## Features
+
+- **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
+
+## Architecture
+
+```
+Agent → MCPClient → ServerRegistry → MCP Servers
+                  ↓
+            Middleware (rate-limit, audit, access-control)
+```
+
+## Usage
+
+### Initialize
+
+```typescript
+import { mcpClient, registerInternalServers } from "@nebutra/mcp";
+
+// Register built-in servers
+registerInternalServers();
+```
+
+### Execute Tools
+
+```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],
+};
+```
+
+## Register Custom Server
+
+```typescript
+import { serverRegistry } from "@nebutra/mcp";
+
+serverRegistry.register({
+  name: "custom-tools",
+  url: "http://localhost:3001/mcp",
+  tools: [
+    {
+      name: "custom_tool",
+      description: "My custom tool",
+      parameters: { type: "object", properties: {} },
+    },
+  ],
+  allowedPlans: ["PRO", "ENTERPRISE"],
+});
+```
+
+## Middleware
+
+### Rate Limiting
+
+```typescript
+// Configured per tool
+const limits = {
+  generate_text: { requests: 100, window: "1m" },
+  embed_text: { requests: 1000, window: "1h" },
+};
+```
+
+### Audit Logging
+
+All tool executions are logged:
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "tool": "generate_text",
+  "tenantId": "org_456",
+  "userId": "user_123",
+  "duration": 245,
+  "success": true
+}
+```
+
+## Related
+
+- [AI service](../../backends/python/ai/)
+- [API Gateway](../../backends/gateway/)

package/bin/nebutra-mcp.js

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

package/dist/server/contextServer.js

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nebutra/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "license": "AGPL-3.0",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "requires": [
+      "@modelcontextprotocol/sdk runtime"
+    ],
+    "gaps": [
+      "No production app integrations",
+      "Context server binary is a placeholder stub",
+      "Tool registry + plan-based access control pending"
+    ],
+    "featureId": "mcp",
+    "category": "ai",
+    "summary": "MCP server primitives (Model Context Protocol)"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./server": "./src/server/index.ts",
+    "./middleware": "./src/middleware/index.ts"
+  },
+  "bin": {
+    "nebutra-mcp": "./dist/server/contextServer.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/client/index.ts

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

package/src/client/mcpClient.ts

@@ -0,0 +1,172 @@
+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;
+
+  /**
+   * 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 = serverRegistry.findServerByTool(toolName);
+    if (!server) {
+      return {
+        success: false,
+        error: `Tool not found: ${toolName}`,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    // Check access
+    if (!serverRegistry.canAccess(server.id, 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 "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");
+  }
+
+  /**
+   * List available tools for a context
+   */
+  listTools(context: MCPContext) {
+    return serverRegistry.getAccessibleTools(context);
+  }
+
+  /**
+   * Get tool definition
+   */
+  getTool(toolName: string, context: MCPContext) {
+    const server = serverRegistry.findServerByTool(toolName);
+    if (!server) return undefined;
+
+    if (!serverRegistry.canAccess(server.id, 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/index.ts

@@ -0,0 +1,23 @@
+// Types
+
+// Client
+export { MCPClient, mcpClient } from "./client/index";
+// Middleware
+export {
+  type AuditLogEntry,
+  composeMCPMiddleware,
+  createAccessControlMiddleware,
+  createAuditMiddleware,
+  createRateLimitMiddleware,
+  type MCPMiddleware,
+  type MCPMiddlewareContext,
+} from "./middleware/index";
+// Registry
+export { MCPServerRegistry, serverRegistry } from "./registry/index";
+// Server
+export {
+  getInternalServerIds,
+  INTERNAL_SERVERS,
+  registerInternalServers,
+} from "./server/index";
+export * from "./types";

package/src/middleware/index.ts

@@ -0,0 +1,10 @@
+export {
+  type AuditLogEntry,
+  composeMCPMiddleware,
+  createAccessControlMiddleware,
+  createAuditMiddleware,
+  createRateLimitMiddleware,
+  type MCPMiddleware,
+  type MCPMiddlewareContext,
+  type MCPMiddlewareNext,
+} from "./mcpMiddleware";

package/src/middleware/mcpMiddleware.ts

@@ -0,0 +1,150 @@
+import type { MCPContext, ToolExecutionResult } from "../types";
+
+/**
+ * MCP Middleware for rate limiting, audit logging, and access control
+ */
+
+export interface MCPMiddlewareContext extends MCPContext {
+  toolName: string;
+  arguments: Record<string, unknown>;
+}
+
+export type MCPMiddlewareNext = () => Promise<ToolExecutionResult>;
+
+export type MCPMiddleware = (
+  ctx: MCPMiddlewareContext,
+  next: MCPMiddlewareNext,
+) => Promise<ToolExecutionResult>;
+
+/**
+ * Rate limiting middleware for MCP calls
+ */
+export function createRateLimitMiddleware(options: {
+  maxRequests: number;
+  windowMs: number;
+}): MCPMiddleware {
+  const requests = new Map<string, { count: number; resetAt: number }>();
+
+  return async (ctx, next) => {
+    const key = `${ctx.tenantId || "anon"}:${ctx.userId || "anon"}`;
+    const now = Date.now();
+
+    let record = requests.get(key);
+    if (!record || now > record.resetAt) {
+      record = { count: 0, resetAt: now + options.windowMs };
+      requests.set(key, record);
+    }
+
+    record.count++;
+
+    if (record.count > options.maxRequests) {
+      return {
+        success: false,
+        error: `MCP rate limit exceeded. Max ${options.maxRequests} requests per ${options.windowMs / 1000}s`,
+        duration: 0,
+      };
+    }
+
+    return next();
+  };
+}
+
+/**
+ * Audit logging middleware
+ */
+export function createAuditMiddleware(options: {
+  onLog: (entry: AuditLogEntry) => void | Promise<void>;
+}): MCPMiddleware {
+  return async (ctx, next) => {
+    const result = await next();
+
+    const entry: AuditLogEntry = {
+      timestamp: new Date().toISOString(),
+      requestId: ctx.requestId,
+      toolName: ctx.toolName,
+      arguments: ctx.arguments,
+      success: result.success,
+      duration: result.duration,
+    };
+
+    if (ctx.tenantId) entry.tenantId = ctx.tenantId;
+    if (ctx.userId) entry.userId = ctx.userId;
+    if (result.error) entry.error = result.error;
+
+    // Don't block on audit logging
+    Promise.resolve(options.onLog(entry)).catch(console.error);
+
+    return result;
+  };
+}
+
+export interface AuditLogEntry {
+  timestamp: string;
+  requestId: string;
+  tenantId?: string;
+  userId?: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+  success: boolean;
+  duration: number;
+  error?: string;
+}
+
+/**
+ * Tool access control middleware
+ */
+export function createAccessControlMiddleware(options: {
+  blockedTools?: string[];
+  allowedTools?: string[];
+}): MCPMiddleware {
+  return async (ctx, next) => {
+    // Check blocked list
+    if (options.blockedTools?.includes(ctx.toolName)) {
+      return {
+        success: false,
+        error: `Tool ${ctx.toolName} is blocked`,
+        duration: 0,
+      };
+    }
+
+    // Check allowed list (if specified)
+    if (
+      options.allowedTools &&
+      options.allowedTools.length > 0 &&
+      !options.allowedTools.includes(ctx.toolName)
+    ) {
+      return {
+        success: false,
+        error: `Tool ${ctx.toolName} is not in allowed list`,
+        duration: 0,
+      };
+    }
+
+    return next();
+  };
+}
+
+/**
+ * Compose multiple middlewares
+ */
+export function composeMCPMiddleware(middlewares: MCPMiddleware[]): MCPMiddleware {
+  return async (ctx, finalNext) => {
+    let index = -1;
+
+    const dispatch = async (i: number): Promise<ToolExecutionResult> => {
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+
+      const middleware = middlewares[i];
+      if (!middleware) {
+        return finalNext();
+      }
+
+      return middleware(ctx, () => dispatch(i + 1));
+    };
+
+    return dispatch(0);
+  };
+}

package/src/registry/index.ts

@@ -0,0 +1 @@
+export { MCPServerRegistry, serverRegistry } from "./serverRegistry";

package/src/registry/serverRegistry.ts

@@ -0,0 +1,128 @@
+import type { MCPContext, MCPServerConfig, ToolDefinition } from "../types";
+
+/**
+ * Registry for MCP servers and their tools
+ * Handles server registration, discovery, and access control
+ */
+export class MCPServerRegistry {
+  private servers: Map<string, MCPServerConfig> = new Map();
+  private toolIndex: Map<string, string> = new Map(); // tool name -> server id
+
+  /**
+   * Register an MCP server
+   */
+  register(config: MCPServerConfig): void {
+    this.servers.set(config.id, config);
+
+    // Index tools for quick lookup
+    for (const tool of config.tools) {
+      const qualifiedName = `${config.id}:${tool.name}`;
+      this.toolIndex.set(qualifiedName, config.id);
+      // Also allow short name if unique
+      if (!this.toolIndex.has(tool.name)) {
+        this.toolIndex.set(tool.name, config.id);
+      }
+    }
+  }
+
+  /**
+   * Unregister an MCP server
+   */
+  unregister(serverId: string): boolean {
+    const server = this.servers.get(serverId);
+    if (!server) return false;
+
+    // Remove tool index entries
+    for (const tool of server.tools) {
+      const qualifiedName = `${serverId}:${tool.name}`;
+      this.toolIndex.delete(qualifiedName);
+      // Only remove short name if it points to this server
+      if (this.toolIndex.get(tool.name) === serverId) {
+        this.toolIndex.delete(tool.name);
+      }
+    }
+
+    this.servers.delete(serverId);
+    return true;
+  }
+
+  /**
+   * Get server by ID
+   */
+  getServer(serverId: string): MCPServerConfig | undefined {
+    return this.servers.get(serverId);
+  }
+
+  /**
+   * Find server by tool name
+   */
+  findServerByTool(toolName: string): MCPServerConfig | undefined {
+    const serverId = this.toolIndex.get(toolName);
+    if (!serverId) return undefined;
+    return this.servers.get(serverId);
+  }
+
+  /**
+   * Get all registered servers
+   */
+  getAllServers(): MCPServerConfig[] {
+    return Array.from(this.servers.values());
+  }
+
+  /**
+   * Get all available tools
+   */
+  getAllTools(): Array<ToolDefinition & { serverId: string }> {
+    const tools: Array<ToolDefinition & { serverId: string }> = [];
+    for (const server of this.servers.values()) {
+      for (const tool of server.tools) {
+        tools.push({ ...tool, serverId: server.id });
+      }
+    }
+    return tools;
+  }
+
+  /**
+   * Check if a context has access to a server
+   */
+  canAccess(serverId: string, context: MCPContext): boolean {
+    const server = this.servers.get(serverId);
+    if (!server) return false;
+
+    // Check plan restrictions
+    if (server.allowedPlans && server.allowedPlans.length > 0) {
+      if (!context.plan || !server.allowedPlans.includes(context.plan)) {
+        return false;
+      }
+    }
+
+    // Check tenant restrictions
+    if (server.allowedTenants && server.allowedTenants.length > 0) {
+      if (!context.tenantId || !server.allowedTenants.includes(context.tenantId)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Get tools accessible by a context
+   */
+  getAccessibleTools(context: MCPContext): Array<ToolDefinition & { serverId: string }> {
+    const tools: Array<ToolDefinition & { serverId: string }> = [];
+
+    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 });
+        }
+      }
+    }
+
+    return tools;
+  }
+}
+
+// Global registry instance
+export const serverRegistry = new MCPServerRegistry();