@celljs/cli 3.8.0 → 4.0.0

package/src/mcp/dev-mcp-endpoint.ts

@@ -0,0 +1,323 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { CellError, type McpToolDefinition } from '@celljs/kit';
+import type { CellDevServer } from '@celljs/vite';
+import { DevActivity, type LogLevel } from './dev-activity.js';
+import { McpServer } from './mcp-server.js';
+
+/** The parts of an inversify 6 container the endpoint reads. */
+interface ContainerLike {
+    get(id: unknown): unknown;
+    parent?: ContainerLike | null;
+    _bindingDictionary?: { getMap(): Map<unknown, BindingLike[]> };
+}
+
+interface BindingLike {
+    type?: string;
+    scope?: string;
+    implementationType?: { name?: string } | null;
+    constraint?: { metaData?: { key?: unknown; value?: unknown } };
+}
+
+interface RouteLike {
+    mapping: Map<string, { path: string | RegExp; controllerMetadata?: { target?: { name?: string } }; methodMetadata?: { key?: unknown } }[]>;
+    errorMapping?: Map<{ name?: string }, { controllerMetadata?: { target?: { name?: string } }; methodMetadata?: { key?: unknown } }>;
+}
+
+/**
+ * `POST /_cell/mcp` of `cell dev`: an MCP endpoint (Streamable HTTP, JSON responses) into the running
+ * application: errors, routes, DI bindings, configuration, recent requests and logs
+ * (docs/design/agent-first.md R8). Only answers same-machine origins.
+ */
+export class DevMcpEndpoint {
+    static readonly PATH = '/_cell/mcp';
+    static readonly MAX_BODY = 1024 * 1024;
+    static readonly LOOPBACK = ['localhost', '127.0.0.1', '[::1]', '::1'];
+    /** A key, not an expression: `get_config` evaluates `${key}`. */
+    static readonly KEY = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*|\[\d+\])*$/;
+
+    readonly server: McpServer;
+
+    constructor(
+        protected readonly dev: () => CellDevServer | undefined,
+        protected readonly activity: DevActivity,
+        version: string,
+    ) {
+        this.server = new McpServer({
+            name: 'cell-dev',
+            version,
+            instructions:
+                'The running Cell application of cell dev. Call get_errors first when something fails; list_routes, list_bindings and get_config show what the application really loaded.',
+            tools: () => this.tools(),
+        });
+    }
+
+    /** A connect-style handler for the dev server. */
+    readonly handler = (req: IncomingMessage, res: ServerResponse): void => {
+        this.handle(req, res).catch(error => {
+            if (!res.headersSent) {
+                DevMcpEndpoint.send(res, 500, McpServer.error(null, error));
+            }
+        });
+    };
+
+    protected async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+        if (!DevMcpEndpoint.sameMachine(req)) {
+            DevMcpEndpoint.send(res, 403, { error: 'Forbidden: the dev MCP endpoint only answers pages and clients of this machine.' });
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.setHeader('Allow', 'POST');
+            DevMcpEndpoint.send(res, 405, { error: 'Use POST with a JSON-RPC message (MCP Streamable HTTP, JSON responses).' });
+            return;
+        }
+        const body = await DevMcpEndpoint.read(req);
+        if (body === undefined) {
+            DevMcpEndpoint.send(res, 413, { error: `The message is larger than ${DevMcpEndpoint.MAX_BODY} bytes.` });
+            return;
+        }
+        const response = await this.server.handleText(body);
+        if (response === undefined) {
+            res.statusCode = 202;
+            res.end();
+            return;
+        }
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(response);
+    }
+
+    /** No Origin (a CLI client), a loopback origin, or the page of the dev server itself. */
+    static sameMachine(req: IncomingMessage): boolean {
+        const origin = req.headers.origin;
+        if (!origin) {
+            return true;
+        }
+        try {
+            const url = new URL(origin);
+            return DevMcpEndpoint.LOOPBACK.includes(url.hostname) || url.host === req.headers.host;
+        } catch {
+            return false;
+        }
+    }
+
+    protected static read(req: IncomingMessage): Promise<string | undefined> {
+        return new Promise((resolve, reject) => {
+            const chunks: Buffer[] = [];
+            let size = 0;
+            req.on('data', (chunk: Buffer) => {
+                size += chunk.length;
+                if (size <= DevMcpEndpoint.MAX_BODY) {
+                    chunks.push(chunk);
+                }
+            });
+            req.on('end', () => resolve(size > DevMcpEndpoint.MAX_BODY ? undefined : Buffer.concat(chunks).toString('utf8')));
+            req.on('error', reject);
+        });
+    }
+
+    protected static send(res: ServerResponse, status: number, body: unknown): void {
+        res.statusCode = status;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(body));
+    }
+
+    tools(): McpToolDefinition[] {
+        const object = (properties: Record<string, unknown> = {}, required: string[] = []) => ({
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+            additionalProperties: false,
+        });
+        const limit = { type: 'integer', description: 'How many of the latest entries (default 20).' };
+        return [
+            {
+                name: 'get_errors',
+                description:
+                    'Why the application fails: the current backend start error (with file, line and fix), earlier failed reloads, requests answered with 5xx and recent error logs.',
+                inputSchema: object(),
+                readOnly: true,
+                run: () => this.errors(),
+            },
+            {
+                name: 'list_routes',
+                description: 'HTTP routes of the running backend (@celljs/mvc): method, path, controller and method name, and error handlers.',
+                inputSchema: object({ filter: { type: 'string', description: 'Only routes whose path or controller contains this text.' } }),
+                readOnly: true,
+                run: input => this.routes(input.filter as string | undefined),
+            },
+            {
+                name: 'list_bindings',
+                description: 'DI bindings of the running container: service identifier, implementation, scope and binding type.',
+                inputSchema: object({
+                    filter: { type: 'string', description: 'Only bindings whose identifier or implementation contains this text (case-insensitive).' },
+                    limit: { type: 'integer', description: 'At most this many (default 200).' },
+                }),
+                readOnly: true,
+                run: input => this.bindings(input.filter as string | undefined, (input.limit as number | undefined) ?? 200),
+            },
+            {
+                name: 'get_config',
+                description:
+                    'A configuration value as the running backend sees it, with ${...} expressions evaluated (e.g. cell.server.port). For where a value comes from, use config_get of cell mcp.',
+                inputSchema: object({ key: { type: 'string', description: 'Dotted key, e.g. cell.server.port.' } }, ['key']),
+                readOnly: true,
+                run: input => this.config(input.key as string),
+            },
+            {
+                name: 'recent_requests',
+                description: 'The latest requests the backend answered: time, method, URL, status and duration.',
+                inputSchema: object({
+                    limit,
+                    minStatus: { type: 'integer', description: 'Only responses with at least this status, e.g. 400.' },
+                    filter: { type: 'string', description: 'Only URLs containing this text.' },
+                }),
+                readOnly: true,
+                run: input => {
+                    const min = (input.minStatus as number | undefined) ?? 0;
+                    const filter = input.filter as string | undefined;
+                    const requests = this.activity.requests.filter(r => r.status >= min && (!filter || r.url.includes(filter)));
+                    return { total: requests.length, requests: requests.slice(-((input.limit as number | undefined) ?? 20)) };
+                },
+            },
+            {
+                name: 'logs',
+                description: 'Console output of the dev process (application, Vite, Cell), newest last.',
+                inputSchema: object({
+                    limit: { type: 'integer', description: 'How many of the latest entries (default 50).' },
+                    level: { type: 'string', enum: DevActivity.LEVELS, description: 'Minimum level (default debug).' },
+                    filter: { type: 'string', description: 'Only messages containing this text.' },
+                }),
+                readOnly: true,
+                run: input => {
+                    const min = DevActivity.LEVELS.indexOf((input.level as LogLevel | undefined) ?? 'debug');
+                    const filter = input.filter as string | undefined;
+                    const logs = this.activity.logs.filter(l => DevActivity.LEVELS.indexOf(l.level) >= min && (!filter || l.message.includes(filter)));
+                    return { total: logs.length, logs: logs.slice(-((input.limit as number | undefined) ?? 50)) };
+                },
+            },
+        ];
+    }
+
+    protected errors(): Record<string, unknown> {
+        const dev = this.dev();
+        return {
+            backend: dev?.error?.toJSON() ?? null,
+            running: Boolean(dev?.application),
+            reloads: this.activity.errors.slice(-5),
+            failedRequests: this.activity.requests.filter(r => r.status >= 500).slice(-10),
+            errorLogs: this.activity.logs.filter(l => l.level === 'error').slice(-10),
+        };
+    }
+
+    protected container(): ContainerLike {
+        const dev = this.dev();
+        const container = dev?.application?.container as ContainerLike | undefined;
+        if (!container) {
+            throw new CellError({
+                code: 'CELL_DEV_BACKEND_NOT_RUNNING',
+                message: dev?.error ? `The backend is not running: ${dev.error.message}` : 'The backend is not running.',
+                hint: dev?.error
+                    ? 'Call get_errors for the details; the backend starts again when a file is saved.'
+                    : 'The project has no backend, or it is still starting.',
+            });
+        }
+        return container;
+    }
+
+    /** Every binding of the container and its parents, by identifier. */
+    protected static entries(container: ContainerLike): [unknown, BindingLike[]][] {
+        const entries: [unknown, BindingLike[]][] = [];
+        for (let c: ContainerLike | null | undefined = container; c; c = c.parent) {
+            const map = c._bindingDictionary?.getMap();
+            if (map) {
+                entries.push(...map.entries());
+            }
+        }
+        return entries;
+    }
+
+    static idName(id: unknown): string {
+        if (typeof id === 'symbol') {
+            return id.description ?? id.toString();
+        }
+        if (typeof id === 'function') {
+            return id.name || '(anonymous class)';
+        }
+        return String(id);
+    }
+
+    /** A service bound under a symbol of that description, e.g. `RouteProvider` of @celljs/mvc. */
+    protected find(description: string): unknown {
+        const container = this.container();
+        const entry = DevMcpEndpoint.entries(container).find(([id]) => typeof id === 'symbol' && id.description === description);
+        return entry && container.get(entry[0]);
+    }
+
+    protected bindings(filter: string | undefined, limit: number): Record<string, unknown> {
+        const needle = filter?.toLowerCase();
+        const rows = DevMcpEndpoint.entries(this.container()).flatMap(([id, bindings]) =>
+            bindings.map(binding => ({
+                id: DevMcpEndpoint.idName(id),
+                ...(binding.implementationType?.name ? { implementation: binding.implementationType.name } : {}),
+                type: binding.type,
+                scope: binding.scope,
+                ...(binding.constraint?.metaData?.key !== undefined
+                    ? { constraint: `${String(binding.constraint.metaData.key)}=${String(binding.constraint.metaData.value)}` }
+                    : {}),
+            })),
+        );
+        const matching = needle ? rows.filter(r => r.id.toLowerCase().includes(needle) || r.implementation?.toLowerCase().includes(needle)) : rows;
+        return { total: matching.length, bindings: matching.slice(0, limit), ...(matching.length > limit ? { truncated: true } : {}) };
+    }
+
+    protected async routes(filter: string | undefined): Promise<Record<string, unknown>> {
+        const provider = this.find('RouteProvider') as { provide(): Promise<RouteLike> } | undefined;
+        if (!provider) {
+            return { routes: [], errorHandlers: [], note: 'The backend has no @celljs/mvc routes.' };
+        }
+        const route = await provider.provide();
+        const routes = [...route.mapping].flatMap(([method, paths]) =>
+            paths.map(p => ({
+                method,
+                path: typeof p.path === 'string' ? p.path : String(p.path),
+                controller: p.controllerMetadata?.target?.name,
+                handler: p.methodMetadata?.key === undefined ? undefined : String(p.methodMetadata.key),
+            })),
+        );
+        const errorHandlers = [...(route.errorMapping ?? [])].map(([type, metadata]) => ({
+            error: type?.name,
+            controller: metadata.controllerMetadata?.target?.name,
+            handler: metadata.methodMetadata?.key === undefined ? undefined : String(metadata.methodMetadata.key),
+        }));
+        const matches = (text?: string) => !filter || (text ?? '').includes(filter);
+        return { routes: routes.filter(r => matches(r.path) || matches(r.controller)), errorHandlers };
+    }
+
+    protected config(key: string): Record<string, unknown> {
+        if (!DevMcpEndpoint.KEY.test(key)) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `Invalid configuration key '${key}'.`,
+                hint: 'Pass a dotted key, e.g. cell.server.port or items[0].name.',
+            });
+        }
+        // ConfigProvider.get() turns 0, false and '' into the default; the expression handler does not.
+        const handler = this.find('ExpressionHandler') as { handle(text: string): unknown } | undefined;
+        if (!handler) {
+            throw new CellError({
+                code: 'CELL_DEV_BACKEND_NOT_RUNNING',
+                message: 'The backend has no ExpressionHandler.',
+                hint: 'Depend on @celljs/core 4 or later.',
+            });
+        }
+        const value = handler.handle(`\${${key}}`);
+        if (value === undefined) {
+            throw new CellError({
+                code: 'CELL_CONFIG_KEY_NOT_FOUND',
+                message: `'${key}' is not set in the running backend.`,
+                hint: `Run cell config get ${key} (or config_get of cell mcp) for the nearest keys and where values come from.`,
+            });
+        }
+        return { key, value };
+    }
+}

package/src/mcp/mcp-server.ts

@@ -0,0 +1,251 @@
+import { CellError, type McpToolDefinition } from '@celljs/kit';
+import { Reporter } from '../cli/reporter.js';
+import { TextUtil } from '../utils/text-util.js';
+
+export interface McpServerOptions {
+    name: string;
+    version: string;
+    /** Told to the client on `initialize`: what the server is for. */
+    instructions?: string;
+    /** The tools, asked for on every `tools/list` and `tools/call` (they may change with the project). */
+    tools(): McpToolDefinition[] | Promise<McpToolDefinition[]>;
+}
+
+type JsonRpcId = string | number | null;
+
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: { code: number; message: string; data?: unknown };
+}
+
+/** A tool result of MCP: the value as JSON text, and as structured content when it is an object. */
+export interface McpToolResult {
+    content: { type: 'text'; text: string }[];
+    structuredContent?: Record<string, unknown>;
+    isError: boolean;
+}
+
+class RpcError extends Error {
+    constructor(
+        readonly code: number,
+        message: string,
+        readonly data?: unknown,
+    ) {
+        super(message);
+    }
+}
+
+/**
+ * The protocol side of an MCP server (JSON-RPC 2.0, tools only), without a transport: `cell mcp`
+ * feeds it lines from stdin, `cell dev` the bodies of POST /_cell/mcp. Tool calls run one at a time;
+ * a failing tool answers with `isError` and the CellError as JSON (docs/design/agent-first.md R5, R8).
+ */
+export class McpServer {
+    static readonly PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+    static readonly PARSE_ERROR = -32700;
+    static readonly INVALID_REQUEST = -32600;
+    static readonly METHOD_NOT_FOUND = -32601;
+    static readonly INVALID_PARAMS = -32602;
+
+    protected queue: Promise<unknown> = Promise.resolve();
+
+    constructor(protected readonly options: McpServerOptions) {}
+
+    /** Handles one line or body of JSON; returns the response text, or undefined for a notification. */
+    async handleText(text: string): Promise<string | undefined> {
+        let message: unknown;
+        try {
+            message = JSON.parse(text);
+        } catch {
+            return JSON.stringify(McpServer.error(null, new RpcError(McpServer.PARSE_ERROR, 'Parse error: the message is not JSON.')));
+        }
+        const response = await this.handle(message);
+        return response && JSON.stringify(response);
+    }
+
+    async handle(message: unknown): Promise<JsonRpcResponse | undefined> {
+        const request = message as JsonRpcRequest;
+        if (typeof request !== 'object' || request === null || Array.isArray(request) || request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
+            // A response from the client (to a request this server never sends) is not an error.
+            if (typeof request === 'object' && request !== null && 'id' in request && ('result' in request || 'error' in request)) {
+                return undefined;
+            }
+            return McpServer.error(null, new RpcError(McpServer.INVALID_REQUEST, 'Invalid request: expected a JSON-RPC 2.0 object with a method.'));
+        }
+        const notification = !('id' in request);
+        try {
+            const result = await this.dispatch(request.method, request.params ?? {});
+            return notification ? undefined : { jsonrpc: '2.0', id: request.id ?? null, result };
+        } catch (error) {
+            return notification ? undefined : McpServer.error(request.id ?? null, error);
+        }
+    }
+
+    protected async dispatch(method: string, params: Record<string, unknown>): Promise<unknown> {
+        switch (method) {
+            case 'initialize': {
+                const requested = params.protocolVersion as string;
+                return {
+                    protocolVersion: McpServer.PROTOCOL_VERSIONS.includes(requested) ? requested : McpServer.PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: this.options.name, version: this.options.version },
+                    ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
+                };
+            }
+            case 'ping':
+                return {};
+            case 'tools/list':
+                return { tools: (await this.options.tools()).map(tool => McpServer.describe(tool)) };
+            case 'tools/call':
+                return this.serialize(() => this.call(params.name, params.arguments));
+            default:
+                if (method.startsWith('notifications/')) {
+                    return {};
+                }
+                throw new RpcError(McpServer.METHOD_NOT_FOUND, `Method not found: ${method}`);
+        }
+    }
+
+    protected serialize<T>(task: () => Promise<T>): Promise<T> {
+        const run = this.queue.then(task, task);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+
+    protected async call(name: unknown, args: unknown = {}): Promise<McpToolResult> {
+        const tools = await this.options.tools();
+        const tool = tools.find(t => t.name === name);
+        if (!tool) {
+            const suggestion =
+                typeof name === 'string'
+                    ? TextUtil.closest(
+                          name,
+                          tools.map(t => t.name),
+                      )
+                    : undefined;
+            throw new RpcError(
+                McpServer.INVALID_PARAMS,
+                `Unknown tool '${String(name)}'.${suggestion ? ` Did you mean '${suggestion}'?` : ` Tools: ${tools.map(t => t.name).join(', ')}.`}`,
+            );
+        }
+        if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+            throw new RpcError(McpServer.INVALID_PARAMS, `The arguments of '${tool.name}' must be an object.`);
+        }
+        const problem = McpServer.validate(tool.inputSchema, args as Record<string, unknown>);
+        if (problem) {
+            return McpServer.result(
+                new CellError({
+                    code: 'CELL_ARGUMENT_INVALID',
+                    message: `Invalid arguments for '${tool.name}': ${problem}`,
+                    hint: 'Call tools/list for the input schema.',
+                }).toJSON(),
+                true,
+            );
+        }
+        try {
+            return McpServer.result(await tool.run(args as Record<string, unknown>), false);
+        } catch (error) {
+            return McpServer.result(Reporter.toCellError(error).toJSON(), true);
+        }
+    }
+
+    static describe(tool: McpToolDefinition): Record<string, unknown> {
+        return {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: { type: 'object', ...tool.inputSchema },
+            annotations: { readOnlyHint: tool.readOnly, destructiveHint: false, openWorldHint: tool.network ?? false },
+        };
+    }
+
+    /** Text for every client; objects also as structured content. */
+    static result(value: unknown, isError: boolean): McpToolResult {
+        const text = typeof value === 'string' ? value : (JSON.stringify(value) ?? 'null');
+        const structured = typeof value === 'object' && value !== null && !Array.isArray(value);
+        return { content: [{ type: 'text', text }], ...(structured ? { structuredContent: value as Record<string, unknown> } : {}), isError };
+    }
+
+    /**
+     * Checks the arguments against the top level of the tool's JSON Schema: required properties, the
+     * type of each property (and of array items), enums, and unknown properties when
+     * `additionalProperties` is false. Returns the first problem, or undefined.
+     */
+    static validate(schema: Record<string, unknown>, args: Record<string, unknown>): string | undefined {
+        const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+        for (const key of (schema.required ?? []) as string[]) {
+            if (args[key] === undefined) {
+                return `'${key}' is required.`;
+            }
+        }
+        for (const [key, value] of Object.entries(args)) {
+            const property = properties[key];
+            if (!property) {
+                if (schema.additionalProperties === false) {
+                    const suggestion = TextUtil.closest(key, Object.keys(properties));
+                    return `unknown property '${key}'.${suggestion ? ` Did you mean '${suggestion}'?` : ` Properties: ${Object.keys(properties).join(', ') || 'none'}.`}`;
+                }
+                continue;
+            }
+            const problem = McpServer.checkValue(value, property);
+            if (problem) {
+                return `'${key}' ${problem}`;
+            }
+        }
+        return undefined;
+    }
+
+    protected static checkValue(value: unknown, schema: Record<string, unknown>): string | undefined {
+        const type = schema.type as string | undefined;
+        if (type && !McpServer.hasType(value, type)) {
+            return `must be ${type === 'array' || type === 'object' || type === 'integer' ? 'an' : 'a'} ${type}.`;
+        }
+        if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+            return `must be one of: ${schema.enum.map(v => JSON.stringify(v)).join(', ')}.`;
+        }
+        if (type === 'array' && schema.items && Array.isArray(value)) {
+            for (const item of value) {
+                const problem = McpServer.checkValue(item, schema.items as Record<string, unknown>);
+                if (problem) {
+                    return `items ${problem}`;
+                }
+            }
+        }
+        return undefined;
+    }
+
+    protected static hasType(value: unknown, type: string): boolean {
+        switch (type) {
+            case 'string':
+                return typeof value === 'string';
+            case 'boolean':
+                return typeof value === 'boolean';
+            case 'number':
+                return typeof value === 'number' && Number.isFinite(value);
+            case 'integer':
+                return Number.isInteger(value);
+            case 'array':
+                return Array.isArray(value);
+            case 'object':
+                return typeof value === 'object' && value !== null && !Array.isArray(value);
+            default:
+                return true;
+        }
+    }
+
+    static error(id: JsonRpcId, error: unknown): JsonRpcResponse {
+        if (error instanceof RpcError) {
+            return { jsonrpc: '2.0', id, error: { code: error.code, message: error.message, ...(error.data === undefined ? {} : { data: error.data }) } };
+        }
+        const cellError = Reporter.toCellError(error);
+        return { jsonrpc: '2.0', id, error: { code: -32603, message: cellError.message, data: cellError.toJSON() } };
+    }
+}