@objectstack/mcp 8.0.0

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+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 `OS_MCP_SERVER_ENABLED` environment variable is set.
+ * 3. **destroy** — Stops the MCP transport.
+ *
+ * Environment Variables:
+ * - `OS_MCP_SERVER_ENABLED=true` — Enable MCP server at startup
+ * - `OS_MCP_SERVER_NAME` — Override server name
+ * - `OS_MCP_SERVER_TRANSPORT` — Override transport ('stdio' | 'http')
+ *   (legacy `MCP_SERVER_*` names still honoured with a deprecation warning)
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { MCPServerPlugin } from '@objectstack/mcp';
+ *
+ * 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;
+}
+
+interface McpObjectSummary {
+    name: string;
+    label?: string;
+    fieldCount?: number;
+}
+/**
+ * Data access seam for the HTTP MCP tools. Implemented by the runtime/dispatcher
+ * so execution flows through the existing permission + RLS path bound to the
+ * caller's ExecutionContext. Every method runs AS the authenticated principal.
+ */
+interface McpDataBridge {
+    listObjects(): Promise<McpObjectSummary[]>;
+    describeObject(name: string): Promise<unknown | null>;
+    query(object: string, opts: {
+        where?: Record<string, unknown>;
+        fields?: string[];
+        limit?: number;
+        offset?: number;
+        orderBy?: Array<{
+            field: string;
+            order: 'asc' | 'desc';
+        }>;
+    }): Promise<unknown>;
+    get(object: string, id: string): Promise<unknown>;
+    create(object: string, data: Record<string, unknown>): Promise<unknown>;
+    update(object: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+    remove(object: string, id: string): Promise<unknown>;
+}
+interface RegisterObjectToolsOptions {
+    /** Expose `sys_*` system objects too. Default false (fail-closed). */
+    allowSystemObjects?: boolean;
+    /** Hard cap on `query_records` page size. Default 50. */
+    maxQueryLimit?: number;
+}
+/**
+ * Register the object-CRUD tool set on a fresh per-request {@link McpServer}.
+ * All execution is delegated to `bridge`, which is bound to the caller's
+ * principal by the runtime.
+ */
+declare function registerObjectTools(server: McpServer, bridge: McpDataBridge, options?: RegisterObjectToolsOptions): void;
+
+/**
+ * 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>;
+    /**
+     * Handle one MCP request over the **Streamable HTTP** transport (Web Standard
+     * `Request`/`Response`), the network-reachable surface for external agents.
+     *
+     * Stateless by design: a fresh {@link McpServer} + transport is built per
+     * request (the SDK-recommended pattern for stateless HTTP — it avoids any
+     * cross-request session/request-id collision and keeps each call isolated).
+     * The tool set is the object-CRUD bridge, bound to the **caller's principal**
+     * via `bridge`; the runtime wires that bridge to the existing permission +
+     * RLS path, so an external agent can never exceed the key's authority.
+     *
+     * Only the object-CRUD tools are exposed here — the internal AI/authoring
+     * toolRegistry (which can mutate metadata) is deliberately NOT bridged onto
+     * the external surface.
+     *
+     * @param request    The inbound Web `Request` (headers/method/url).
+     * @param opts.bridge       Principal-bound data accessor (required to expose tools).
+     * @param opts.parsedBody   Pre-parsed JSON-RPC body (the dispatcher already read it).
+     * @param opts.authInfo     Optional auth info forwarded to message handlers.
+     * @param opts.toolOptions  Object-tool exposure options (system objects, limits).
+     */
+    handleHttpRequest(request: Request, opts?: {
+        bridge?: McpDataBridge;
+        parsedBody?: unknown;
+        authInfo?: unknown;
+        toolOptions?: RegisterObjectToolsOptions;
+    }): Promise<Response>;
+}
+
+/**
+ * skill — the generic, portable ObjectStack Agent Skill.
+ *
+ * Per ADR-0036 (Amendment C): the cross-agent distributable is ONE generic
+ * Skill, not per-app artifacts and not hand-maintained vendor config snippets.
+ * Agent Skills (`SKILL.md`) is an open, cross-platform standard (Claude Code,
+ * OpenAI Codex, Gemini CLI, Copilot, Cursor, …), so this single skill teaches
+ * any skills-capable agent how to drive an ObjectStack environment over MCP.
+ *
+ * The skill content is GENERIC — it never enumerates a tenant's schema (that is
+ * discovered live via the `list_objects` / `describe_object` MCP tools). Only
+ * the connection URL is environment-specific, slotted in by
+ * {@link renderSkillMarkdown}. So one skill install works for every env and
+ * every app the caller's key can reach; building a new app needs no reinstall.
+ *
+ * This module is the single source of truth for the skill; serve it (objectui /
+ * cloud) by calling {@link renderSkillMarkdown} with the env's MCP URL.
+ */
+/** Skill identity (mirrors the `SKILL.md` YAML frontmatter). */
+declare const OBJECTSTACK_SKILL_NAME = "objectstack";
+declare const OBJECTSTACK_SKILL_DESCRIPTION: string;
+interface RenderSkillOptions {
+    /**
+     * The environment's MCP endpoint, e.g. `https://acme.objectos.app/api/v1/mcp`.
+     * When omitted a clearly-marked placeholder is used so the skill is still
+     * valid and self-explanatory.
+     */
+    mcpUrl?: string;
+    /** Optional human label for the environment, shown in the intro. */
+    envName?: string;
+}
+/**
+ * Render the full `SKILL.md` (YAML frontmatter + body). Pass the env's MCP URL
+ * to produce a ready-to-install skill; the body is otherwise generic.
+ */
+declare function renderSkillMarkdown(options?: RenderSkillOptions): string;
+
+export { MCPServerPlugin, type MCPServerPluginOptions, MCPServerRuntime, type MCPServerRuntimeConfig, type McpDataBridge, type McpObjectSummary, OBJECTSTACK_SKILL_DESCRIPTION, OBJECTSTACK_SKILL_NAME, type RegisterObjectToolsOptions, type RenderSkillOptions, registerObjectTools, renderSkillMarkdown };