@nebutra/mcp 0.1.0 → 0.1.1

package/dist/chunk-YMTQFRV2.js

@@ -0,0 +1,178 @@
+// src/server/contextServer.ts
+import fs from "fs";
+import path from "path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var NebutraContextServer = class {
+  server;
+  projectRoot;
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot || process.cwd();
+    this.server = new Server(
+      {
+        name: "@nebutra/context-server",
+        version: "0.1.0"
+      },
+      {
+        capabilities: {
+          resources: {},
+          tools: {}
+        }
+      }
+    );
+    this.setupResourceHandlers();
+    this.setupToolHandlers();
+    this.server.onerror = (_error) => {
+    };
+  }
+  setupResourceHandlers() {
+    const handlers = createContextServerHandlers(this.projectRoot);
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => handlers.listResources());
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      return handlers.readResource(request.params);
+    });
+  }
+  setupToolHandlers() {
+    const handlers = createContextServerHandlers(this.projectRoot);
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => handlers.listTools());
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      return handlers.callTool(request.params);
+    });
+  }
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+};
+var RESOURCE_MAP = {
+  "file:///nebutra.config.json": {
+    relativePath: "nebutra.config.json",
+    name: "Nebutra Configuration",
+    mimeType: "application/json",
+    description: "Global configurations for the Nebutra template including enabled features (auth, payments, i18n, db)."
+  },
+  "file:///prisma/schema.prisma": {
+    relativePath: "packages/platform/db/prisma/schema.prisma",
+    name: "Database Schema Overview",
+    mimeType: "text/plain",
+    description: "The core Prisma schema defining the database tables and relationships."
+  }
+};
+function createContextServerHandlers(projectRoot) {
+  return {
+    async listResources() {
+      return {
+        resources: Object.entries(RESOURCE_MAP).map(([uri, resource]) => ({
+          uri,
+          name: resource.name,
+          mimeType: resource.mimeType,
+          description: resource.description
+        }))
+      };
+    },
+    async readResource({ uri }) {
+      const resource = RESOURCE_MAP[uri];
+      if (!resource) {
+        throw new Error(`Resource not found: ${uri}`);
+      }
+      const filePath = path.join(projectRoot, resource.relativePath);
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: resource.mimeType,
+              text: content
+            }
+          ]
+        };
+      } catch {
+        throw new Error(`Failed to read the requested resource file at ${filePath}`);
+      }
+    },
+    async listTools() {
+      return {
+        tools: [
+          {
+            name: "get_project_structure",
+            description: "Returns a bounded app/package routing tree for the current project.",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: []
+            }
+          }
+        ]
+      };
+    },
+    async callTool({ name }) {
+      if (name !== "get_project_structure") {
+        throw new Error(`Unknown tool: ${name}`);
+      }
+      try {
+        return {
+          content: [
+            {
+              type: "text",
+              text: getProjectStructure(projectRoot)
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  };
+}
+function getProjectStructure(projectRoot) {
+  const roots = ["apps", "packages", "backends"].filter(
+    (segment) => fs.existsSync(path.join(projectRoot, segment))
+  );
+  if (roots.length === 0) return "No Nebutra workspace roots found.";
+  const entries = [];
+  for (const root of roots) {
+    walkProjectTree(path.join(projectRoot, root), root, entries, 4);
+  }
+  return entries.length > 0 ? entries.join("\n") : "No project entries found.";
+}
+function walkProjectTree(absoluteDir, relativeDir, entries, depthRemaining) {
+  if (depthRemaining < 0 || entries.length >= 200) return;
+  entries.push(relativeDir);
+  for (const dirent of fs.readdirSync(absoluteDir, { withFileTypes: true })) {
+    if (!dirent.isDirectory()) continue;
+    if (dirent.name === "node_modules" || dirent.name.startsWith(".")) continue;
+    walkProjectTree(
+      path.join(absoluteDir, dirent.name),
+      path.join(relativeDir, dirent.name),
+      entries,
+      depthRemaining - 1
+    );
+  }
+}
+var startContextServer = () => {
+  const server = new NebutraContextServer();
+  server.run().catch(console.error);
+};
+if (process.argv[1]?.endsWith("contextServer.js") || process.argv[1]?.endsWith("nebutra-mcp")) {
+  startContextServer();
+}
+
+export {
+  createContextServerHandlers,
+  startContextServer
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,55 @@
+import {
+  McpHost,
+  readToolDebug
+} from "./chunk-ORGYGQJV.js";
+import {
+  createContextServerHandlers
+} from "./chunk-YMTQFRV2.js";
+
+// src/cli.ts
+var command = process.argv[2] ?? "doctor";
+var host = new McpHost();
+var 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)}
+`
+  );
+} 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)}
+`
+  );
+} 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)}
+`
+  );
+} else {
+  process.stderr.write(`Unknown tool-protocol command: ${command}
+`);
+  process.exitCode = 1;
+}

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import { z } from 'zod';
+import { EventLog } from '@nebutra/event-log';
+import { TraceStore } from '@nebutra/trace-store';
+
+declare const ToolParameterSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        array: "array";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+declare const ToolDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            array: "array";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>>>;
+    returns: z.ZodOptional<z.ZodString>;
+    allowedPlans: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedTenants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requiredPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type ToolParameter = z.infer<typeof ToolParameterSchema>;
+type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
+interface MCPRequest {
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface MCPResponse {
+    id: string;
+    result?: unknown;
+    error?: MCPError;
+}
+interface MCPError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface MCPContext {
+    requestId: string;
+    tenantId?: string;
+    userId?: string;
+    plan?: string;
+    permissions?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface ToolExecutionRequest {
+    tool: string;
+    arguments: Record<string, unknown>;
+    context: MCPContext;
+}
+interface ToolExecutionResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    duration: number;
+    tokensUsed?: number;
+}
+interface MCPServerManifest {
+    name: string;
+    version: string;
+    scopes: string[];
+    homepage?: string;
+}
+interface MCPServerConfig {
+    id: string;
+    name: string;
+    description: string;
+    endpoint: string;
+    transport: "http" | "websocket" | "stdio" | "local";
+    manifest?: MCPServerManifest;
+    tools: ToolDefinition[];
+    handlers?: Record<string, MCPToolHandler>;
+    authentication?: {
+        type: "bearer" | "api-key" | "none";
+        headerName?: string;
+    };
+    rateLimit?: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    allowedPlans?: string[];
+    allowedTenants?: string[];
+}
+type MCPToolHandler = (args: Record<string, unknown>, context: MCPContext) => unknown | Promise<unknown>;
+interface SmitheryServerInfo {
+    qualifiedName: string;
+    displayName: string;
+    description: string;
+    homepage?: string;
+    useCount?: number;
+    isDeployed?: boolean;
+}
+interface SmitheryConfig {
+    apiKey?: string;
+    baseUrl: string;
+    defaultServers?: string[];
+}
+
+/**
+ * Registry for MCP servers and their tools
+ * Handles server registration, discovery, and access control
+ */
+declare class MCPServerRegistry {
+    private servers;
+    private toolIndex;
+    /**
+     * Register an MCP server
+     */
+    register(config: MCPServerConfig): void;
+    /**
+     * Unregister an MCP server
+     */
+    unregister(serverId: string): boolean;
+    /**
+     * Get server by ID
+     */
+    getServer(serverId: string): MCPServerConfig | undefined;
+    /**
+     * Find server by tool name
+     */
+    findServerByTool(toolName: string): MCPServerConfig | undefined;
+    /**
+     * Get all registered servers
+     */
+    getAllServers(): MCPServerConfig[];
+    /**
+     * Get all available tools
+     */
+    getAllTools(): Array<ToolDefinition & {
+        serverId: string;
+    }>;
+    /**
+     * Check if a context has access to a server
+     */
+    canAccess(serverId: string, context: MCPContext): boolean;
+    /**
+     * Check whether a context can execute a specific tool. Tool-level policy
+     * narrows the server policy and supports tenant, plan, and permission gates.
+     */
+    canAccessTool(toolName: string, context: MCPContext): boolean;
+    /**
+     * Get tools accessible by a context
+     */
+    getAccessibleTools(context: MCPContext): Array<ToolDefinition & {
+        serverId: string;
+    }>;
+    private findTool;
+}
+declare const serverRegistry: MCPServerRegistry;
+
+/**
+ * MCP Client for executing tools across registered servers
+ */
+declare class MCPClient {
+    private readonly registry;
+    private requestCounter;
+    constructor(registry?: MCPServerRegistry);
+    /**
+     * Execute a tool by name
+     */
+    executeTool(toolName: string, args: Record<string, unknown>, context: MCPContext): Promise<ToolExecutionResult>;
+    /**
+     * Execute tool on a specific server
+     */
+    private executeOnServer;
+    /**
+     * Execute via HTTP transport
+     */
+    private executeHttp;
+    /**
+     * Execute via WebSocket transport
+     */
+    private executeWebSocket;
+    private executeLocal;
+    /**
+     * List available tools for a context
+     */
+    listTools(context: MCPContext): ({
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description?: string | undefined;
+            required?: boolean | undefined;
+            default?: any;
+        }> | undefined;
+        returns?: string | undefined;
+        allowedPlans?: string[] | undefined;
+        allowedTenants?: string[] | undefined;
+        requiredPermissions?: string[] | undefined;
+    } & {
+        serverId: string;
+    })[];
+    /**
+     * Get tool definition
+     */
+    getTool(toolName: string, context: MCPContext): {
+        name: string;
+        description: string;
+        parameters?: Record<string, {
+            type: "string" | "number" | "boolean" | "object" | "array";
+            description?: string | undefined;
+            required?: boolean | undefined;
+            default?: any;
+        }> | undefined;
+        returns?: string | undefined;
+        allowedPlans?: string[] | undefined;
+        allowedTenants?: string[] | undefined;
+        requiredPermissions?: string[] | undefined;
+    } | undefined;
+}
+declare const mcpClient: MCPClient;
+
+interface ToolConsentGrant {
+    readonly tenantId: string;
+    readonly userId?: string;
+    readonly serverId: string;
+    readonly toolName: string;
+    readonly scopes: readonly string[];
+}
+interface ToolConsentStore {
+    grant(grant: ToolConsentGrant): Promise<void>;
+    hasConsent(grant: ToolConsentGrant): Promise<boolean>;
+    list(tenantId?: string): Promise<ToolConsentGrant[]>;
+}
+declare class InMemoryToolConsentStore implements ToolConsentStore {
+    #private;
+    grant(grant: ToolConsentGrant): Promise<void>;
+    hasConsent(grant: ToolConsentGrant): Promise<boolean>;
+    list(tenantId?: string): Promise<ToolConsentGrant[]>;
+}
+
+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;
+}
+declare function toolDebugPath(): string;
+declare function appendToolDebug(entry: Omit<ToolDebugEntry, "at"> & {
+    at?: string;
+}): Promise<void>;
+declare function readToolDebug(limit?: number): Promise<ToolDebugEntry[]>;
+
+interface McpHostOptions {
+    readonly registry?: MCPServerRegistry;
+    readonly consent?: ToolConsentStore;
+    readonly traceStore?: TraceStore;
+    readonly eventLog?: EventLog;
+}
+interface LocalMcpServerConfig {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly manifest?: MCPServerManifest;
+    readonly tools: readonly ToolDefinition[];
+    readonly handlers: Record<string, MCPToolHandler>;
+    readonly allowedPlans?: readonly string[];
+    readonly allowedTenants?: readonly string[];
+}
+interface RemoteMcpConnectOptions {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly manifest: MCPServerManifest;
+    readonly headers?: Record<string, string>;
+}
+declare class McpHost {
+    #private;
+    constructor(options?: McpHostOptions);
+    get registry(): MCPServerRegistry;
+    connectLocal(config: LocalMcpServerConfig): void;
+    connectStdio(command: string, args: readonly string[], options: RemoteMcpConnectOptions): Promise<void>;
+    connectStreamableHttp(endpoint: string, options: RemoteMcpConnectOptions): Promise<void>;
+    callTool(toolName: string, args: Record<string, unknown>, context: MCPContext): Promise<ToolExecutionResult>;
+    listTools(context: MCPContext): Array<ToolDefinition & {
+        serverId: string;
+    }>;
+    inspect(serverId: string): MCPServerConfig;
+    doctor(): Promise<{
+        ok: boolean;
+        servers: Array<{
+            id: string;
+            name: string;
+            transport: MCPServerConfig["transport"];
+            tools: number;
+            manifest?: MCPServerManifest;
+        }>;
+        suggestion?: string;
+    }>;
+    debug(limit?: number): Promise<ToolDebugEntry[]>;
+    close(): Promise<void>;
+}
+declare const toolConsentStore: InMemoryToolConsentStore;
+declare const mcpHost: McpHost;
+
+/**
+ * MCP Middleware for rate limiting, audit logging, and access control
+ */
+interface MCPMiddlewareContext extends MCPContext {
+    toolName: string;
+    arguments: Record<string, unknown>;
+}
+type MCPMiddlewareNext = () => Promise<ToolExecutionResult>;
+type MCPMiddleware = (ctx: MCPMiddlewareContext, next: MCPMiddlewareNext) => Promise<ToolExecutionResult>;
+/**
+ * Rate limiting middleware for MCP calls
+ */
+declare function createRateLimitMiddleware(options: {
+    maxRequests: number;
+    windowMs: number;
+}): MCPMiddleware;
+/**
+ * Audit logging middleware
+ */
+declare function createAuditMiddleware(options: {
+    onLog: (entry: AuditLogEntry) => void | Promise<void>;
+}): MCPMiddleware;
+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
+ */
+declare function createAccessControlMiddleware(options: {
+    blockedTools?: string[];
+    allowedTools?: string[];
+}): MCPMiddleware;
+/**
+ * Compose multiple middlewares
+ */
+declare function composeMCPMiddleware(middlewares: MCPMiddleware[]): MCPMiddleware;
+
+/**
+ * Register internal Nebutra services as MCP servers
+ * These wrap our existing microservices with MCP-compatible interfaces
+ */
+declare const INTERNAL_SERVERS: MCPServerConfig[];
+/**
+ * Register all internal servers
+ */
+declare function registerInternalServers(): void;
+/**
+ * Get list of internal server IDs
+ */
+declare function getInternalServerIds(): string[];
+
+export { type AuditLogEntry, INTERNAL_SERVERS, InMemoryToolConsentStore, MCPClient, type MCPContext, type MCPError, type MCPMiddleware, type MCPMiddlewareContext, type MCPRequest, type MCPResponse, type MCPServerConfig, type MCPServerManifest, MCPServerRegistry, type MCPToolHandler, McpHost, type SmitheryConfig, type SmitheryServerInfo, type ToolConsentGrant, type ToolConsentStore, type ToolDebugEntry, type ToolDefinition, ToolDefinitionSchema, type ToolExecutionRequest, type ToolExecutionResult, type ToolParameter, ToolParameterSchema, appendToolDebug, composeMCPMiddleware, createAccessControlMiddleware, createAuditMiddleware, createRateLimitMiddleware, getInternalServerIds, mcpClient, mcpHost, readToolDebug, registerInternalServers, serverRegistry, toolConsentStore, toolDebugPath };

package/dist/index.js

@@ -0,0 +1,44 @@
+import {
+  INTERNAL_SERVERS,
+  InMemoryToolConsentStore,
+  MCPClient,
+  MCPServerRegistry,
+  McpHost,
+  ToolDefinitionSchema,
+  ToolParameterSchema,
+  appendToolDebug,
+  composeMCPMiddleware,
+  createAccessControlMiddleware,
+  createAuditMiddleware,
+  createRateLimitMiddleware,
+  getInternalServerIds,
+  mcpClient,
+  mcpHost,
+  readToolDebug,
+  registerInternalServers,
+  serverRegistry,
+  toolConsentStore,
+  toolDebugPath
+} from "./chunk-ORGYGQJV.js";
+export {
+  INTERNAL_SERVERS,
+  InMemoryToolConsentStore,
+  MCPClient,
+  MCPServerRegistry,
+  McpHost,
+  ToolDefinitionSchema,
+  ToolParameterSchema,
+  appendToolDebug,
+  composeMCPMiddleware,
+  createAccessControlMiddleware,
+  createAuditMiddleware,
+  createRateLimitMiddleware,
+  getInternalServerIds,
+  mcpClient,
+  mcpHost,
+  readToolDebug,
+  registerInternalServers,
+  serverRegistry,
+  toolConsentStore,
+  toolDebugPath
+};

package/dist/server/contextServer.d.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+declare function createContextServerHandlers(projectRoot: string): {
+    listResources(): Promise<{
+        resources: {
+            uri: string;
+            name: "Nebutra Configuration" | "Database Schema Overview";
+            mimeType: "application/json" | "text/plain";
+            description: "Global configurations for the Nebutra template including enabled features (auth, payments, i18n, db)." | "The core Prisma schema defining the database tables and relationships.";
+        }[];
+    }>;
+    readResource({ uri }: {
+        uri: string;
+    }): Promise<{
+        contents: {
+            uri: string;
+            mimeType: "application/json" | "text/plain";
+            text: string;
+        }[];
+    }>;
+    listTools(): Promise<{
+        tools: {
+            name: string;
+            description: string;
+            inputSchema: {
+                type: string;
+                properties: {};
+                required: never[];
+            };
+        }[];
+    }>;
+    callTool({ name }: {
+        name: string;
+        arguments?: Record<string, unknown> | undefined;
+    }): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: never;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+declare const startContextServer: () => void;
+
+export { createContextServerHandlers, startContextServer };