@objectstack/plugin-mcp-server 4.0.2

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AIToolDefinition, ToolCallPart, ToolResultPart, Logger, IMetadataService, IDataEngine } from '@objectstack/spec/contracts';
+
+/**
+ * Configuration options for the MCPServerPlugin.
+ */
+interface MCPServerPluginOptions {
+    /** Override MCP server name. Defaults to 'objectstack'. */
+    name?: string;
+    /** Override MCP server version. Defaults to package version. */
+    version?: string;
+    /** Transport mode: 'stdio' (default). */
+    transport?: 'stdio' | 'http';
+    /** Whether to auto-start the MCP server. Defaults to false (manual start via env var). */
+    autoStart?: boolean;
+    /** Custom instructions for the MCP server. */
+    instructions?: string;
+}
+/**
+ * MCPServerPlugin — Kernel plugin that exposes ObjectStack as an MCP server.
+ *
+ * Lifecycle:
+ * 1. **init** — Creates {@link MCPServerRuntime} and registers as `'mcp'` service.
+ * 2. **start** — Bridges ToolRegistry, MetadataService, DataEngine, and Agents
+ *    to the MCP server. Starts the transport if `autoStart` is enabled or
+ *    the `MCP_SERVER_ENABLED` environment variable is set.
+ * 3. **destroy** — Stops the MCP transport.
+ *
+ * Environment Variables:
+ * - `MCP_SERVER_ENABLED=true` — Enable MCP server at startup
+ * - `MCP_SERVER_NAME` — Override server name
+ * - `MCP_SERVER_TRANSPORT` — Override transport ('stdio' | 'http')
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { MCPServerPlugin } from '@objectstack/plugin-mcp-server';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new MCPServerPlugin({ autoStart: true }));
+ * await kernel.bootstrap();
+ * ```
+ */
+declare class MCPServerPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private runtime?;
+    private readonly options;
+    constructor(options?: MCPServerPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Minimal ToolRegistry interface consumed by the MCP bridge.
+ *
+ * Matches the public API of `ToolRegistry` from `@objectstack/service-ai`
+ * without creating a hard dependency on that package.
+ */
+interface ToolRegistry {
+    /** Return all registered tool definitions. */
+    getAll(): AIToolDefinition[];
+    /** Execute a tool call and return the result. */
+    execute(toolCall: ToolCallPart): Promise<ToolExecutionResult>;
+}
+/**
+ * Extended ToolResultPart with isError flag, matching service-ai's ToolExecutionResult.
+ */
+interface ToolExecutionResult extends ToolResultPart {
+    isError?: boolean;
+}
+
+/**
+ * Configuration for the MCP Server Runtime.
+ */
+interface MCPServerRuntimeConfig {
+    /** Human-readable server name. */
+    name?: string;
+    /** Server version (semver). */
+    version?: string;
+    /** Optional instructions describing how to use the server. */
+    instructions?: string;
+    /** Transport mode: 'stdio' (default) or 'http'. */
+    transport?: 'stdio' | 'http';
+    /** Logger instance. */
+    logger?: Logger;
+}
+/**
+ * MCPServerRuntime — Bridges ObjectStack kernel services to the Model Context Protocol.
+ *
+ * Responsibilities:
+ * 1. Bridge ToolRegistry → MCP tools (all registered AI tools)
+ * 2. Bridge IMetadataService → MCP resources (object schemas, metadata types)
+ * 3. Bridge IDataEngine → MCP resources (record access by URI)
+ * 4. Bridge Agent definitions → MCP prompts (agent instructions)
+ *
+ * Architecture:
+ * ```
+ * ToolRegistry (service-ai)  ──┐
+ * IMetadataService (metadata) ─┼──→  MCPServerRuntime  ──→  McpServer (SDK)
+ * IDataEngine (objectql)     ──┤                              │
+ * Agent definitions          ──┘                              ├── stdio transport
+ *                                                             └── http transport (future)
+ * ```
+ */
+declare class MCPServerRuntime {
+    private readonly mcpServer;
+    private readonly config;
+    private transport;
+    private started;
+    constructor(config?: MCPServerRuntimeConfig);
+    /** The underlying McpServer instance (for advanced use cases). */
+    get server(): McpServer;
+    /** Whether the server is currently connected and running. */
+    get isStarted(): boolean;
+    /**
+     * Extract the text value from a ToolExecutionResult's output.
+     *
+     * The output may be a `{ type: 'text', value: string }` object (from the
+     * Vercel AI SDK ToolResultPart) or any serialisable value.
+     */
+    private static formatToolOutput;
+    /**
+     * Bridge all tools from the ToolRegistry to MCP tools.
+     *
+     * Each registered tool becomes an MCP tool with the same name, description,
+     * and JSON Schema parameters. The handler delegates to the ToolRegistry's
+     * execute path.
+     */
+    bridgeTools(toolRegistry: ToolRegistry): void;
+    /**
+     * Register a single tool on the MCP server from an AIToolDefinition.
+     */
+    private registerToolFromDefinition;
+    /**
+     * Check if a tool is read-only (data query tools).
+     */
+    private isReadOnlyTool;
+    /**
+     * Check if a tool performs destructive operations.
+     */
+    private isDestructiveTool;
+    /**
+     * Bridge metadata service and data engine to MCP resources.
+     *
+     * Exposes:
+     * - `objectstack://objects` — List all data objects
+     * - `objectstack://objects/{objectName}` — Get object schema
+     * - `objectstack://objects/{objectName}/records/{recordId}` — Get a specific record
+     * - `objectstack://metadata/types` — List all metadata types
+     */
+    bridgeResources(metadataService: IMetadataService, dataEngine?: IDataEngine): void;
+    /**
+     * Bridge registered agents to MCP prompts.
+     *
+     * Each active agent becomes an MCP prompt with:
+     * - Name matching the agent name
+     * - System message from agent instructions
+     * - Optional context arguments (objectName, recordId, viewName)
+     */
+    bridgePrompts(metadataService: IMetadataService): void;
+    /**
+     * Start the MCP server with the configured transport.
+     *
+     * For stdio transport, this connects to process stdin/stdout.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the MCP server and disconnect the transport.
+     */
+    stop(): Promise<void>;
+}
+
+export { MCPServerPlugin, type MCPServerPluginOptions, MCPServerRuntime, type MCPServerRuntimeConfig };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AIToolDefinition, ToolCallPart, ToolResultPart, Logger, IMetadataService, IDataEngine } from '@objectstack/spec/contracts';
+
+/**
+ * Configuration options for the MCPServerPlugin.
+ */
+interface MCPServerPluginOptions {
+    /** Override MCP server name. Defaults to 'objectstack'. */
+    name?: string;
+    /** Override MCP server version. Defaults to package version. */
+    version?: string;
+    /** Transport mode: 'stdio' (default). */
+    transport?: 'stdio' | 'http';
+    /** Whether to auto-start the MCP server. Defaults to false (manual start via env var). */
+    autoStart?: boolean;
+    /** Custom instructions for the MCP server. */
+    instructions?: string;
+}
+/**
+ * MCPServerPlugin — Kernel plugin that exposes ObjectStack as an MCP server.
+ *
+ * Lifecycle:
+ * 1. **init** — Creates {@link MCPServerRuntime} and registers as `'mcp'` service.
+ * 2. **start** — Bridges ToolRegistry, MetadataService, DataEngine, and Agents
+ *    to the MCP server. Starts the transport if `autoStart` is enabled or
+ *    the `MCP_SERVER_ENABLED` environment variable is set.
+ * 3. **destroy** — Stops the MCP transport.
+ *
+ * Environment Variables:
+ * - `MCP_SERVER_ENABLED=true` — Enable MCP server at startup
+ * - `MCP_SERVER_NAME` — Override server name
+ * - `MCP_SERVER_TRANSPORT` — Override transport ('stdio' | 'http')
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { MCPServerPlugin } from '@objectstack/plugin-mcp-server';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new MCPServerPlugin({ autoStart: true }));
+ * await kernel.bootstrap();
+ * ```
+ */
+declare class MCPServerPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private runtime?;
+    private readonly options;
+    constructor(options?: MCPServerPluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Minimal ToolRegistry interface consumed by the MCP bridge.
+ *
+ * Matches the public API of `ToolRegistry` from `@objectstack/service-ai`
+ * without creating a hard dependency on that package.
+ */
+interface ToolRegistry {
+    /** Return all registered tool definitions. */
+    getAll(): AIToolDefinition[];
+    /** Execute a tool call and return the result. */
+    execute(toolCall: ToolCallPart): Promise<ToolExecutionResult>;
+}
+/**
+ * Extended ToolResultPart with isError flag, matching service-ai's ToolExecutionResult.
+ */
+interface ToolExecutionResult extends ToolResultPart {
+    isError?: boolean;
+}
+
+/**
+ * Configuration for the MCP Server Runtime.
+ */
+interface MCPServerRuntimeConfig {
+    /** Human-readable server name. */
+    name?: string;
+    /** Server version (semver). */
+    version?: string;
+    /** Optional instructions describing how to use the server. */
+    instructions?: string;
+    /** Transport mode: 'stdio' (default) or 'http'. */
+    transport?: 'stdio' | 'http';
+    /** Logger instance. */
+    logger?: Logger;
+}
+/**
+ * MCPServerRuntime — Bridges ObjectStack kernel services to the Model Context Protocol.
+ *
+ * Responsibilities:
+ * 1. Bridge ToolRegistry → MCP tools (all registered AI tools)
+ * 2. Bridge IMetadataService → MCP resources (object schemas, metadata types)
+ * 3. Bridge IDataEngine → MCP resources (record access by URI)
+ * 4. Bridge Agent definitions → MCP prompts (agent instructions)
+ *
+ * Architecture:
+ * ```
+ * ToolRegistry (service-ai)  ──┐
+ * IMetadataService (metadata) ─┼──→  MCPServerRuntime  ──→  McpServer (SDK)
+ * IDataEngine (objectql)     ──┤                              │
+ * Agent definitions          ──┘                              ├── stdio transport
+ *                                                             └── http transport (future)
+ * ```
+ */
+declare class MCPServerRuntime {
+    private readonly mcpServer;
+    private readonly config;
+    private transport;
+    private started;
+    constructor(config?: MCPServerRuntimeConfig);
+    /** The underlying McpServer instance (for advanced use cases). */
+    get server(): McpServer;
+    /** Whether the server is currently connected and running. */
+    get isStarted(): boolean;
+    /**
+     * Extract the text value from a ToolExecutionResult's output.
+     *
+     * The output may be a `{ type: 'text', value: string }` object (from the
+     * Vercel AI SDK ToolResultPart) or any serialisable value.
+     */
+    private static formatToolOutput;
+    /**
+     * Bridge all tools from the ToolRegistry to MCP tools.
+     *
+     * Each registered tool becomes an MCP tool with the same name, description,
+     * and JSON Schema parameters. The handler delegates to the ToolRegistry's
+     * execute path.
+     */
+    bridgeTools(toolRegistry: ToolRegistry): void;
+    /**
+     * Register a single tool on the MCP server from an AIToolDefinition.
+     */
+    private registerToolFromDefinition;
+    /**
+     * Check if a tool is read-only (data query tools).
+     */
+    private isReadOnlyTool;
+    /**
+     * Check if a tool performs destructive operations.
+     */
+    private isDestructiveTool;
+    /**
+     * Bridge metadata service and data engine to MCP resources.
+     *
+     * Exposes:
+     * - `objectstack://objects` — List all data objects
+     * - `objectstack://objects/{objectName}` — Get object schema
+     * - `objectstack://objects/{objectName}/records/{recordId}` — Get a specific record
+     * - `objectstack://metadata/types` — List all metadata types
+     */
+    bridgeResources(metadataService: IMetadataService, dataEngine?: IDataEngine): void;
+    /**
+     * Bridge registered agents to MCP prompts.
+     *
+     * Each active agent becomes an MCP prompt with:
+     * - Name matching the agent name
+     * - System message from agent instructions
+     * - Optional context arguments (objectName, recordId, viewName)
+     */
+    bridgePrompts(metadataService: IMetadataService): void;
+    /**
+     * Start the MCP server with the configured transport.
+     *
+     * For stdio transport, this connects to process stdin/stdout.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the MCP server and disconnect the transport.
+     */
+    stop(): Promise<void>;
+}
+
+export { MCPServerPlugin, type MCPServerPluginOptions, MCPServerRuntime, type MCPServerRuntimeConfig };