@celljs/cli 3.9.0 → 4.0.0

package/src/mcp/project-mcp-tools.ts

@@ -0,0 +1,216 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CellError, type McpToolDefinition } from '@celljs/kit';
+import { Toolchain } from '../toolchain/toolchain.js';
+
+/** Runs `cell <argv>` in this process and returns what it printed. */
+export type CellRunner = (argv: string[]) => Promise<{ code: number; stdout: string }>;
+
+/**
+ * The tools of `cell mcp` (docs/design/agent-first.md R8): `info`, `check`, `config_get`,
+ * `docs_search`, `build` and `deploy_plan` (`cell deploy --dry-run`) run the commands with `--json`
+ * and return their result, so the two interfaces never disagree. Deploying is not a tool. Tools of toolchain modules (`cell.addMcpTool`)
+ * follow; the toolchain is loaded again when cell.config.*, package.json or a module file changes.
+ */
+export class ProjectMcpTools {
+    protected toolchain?: Toolchain;
+    protected fingerprint = '';
+    protected moduleTools: McpToolDefinition[] = [];
+
+    constructor(
+        protected readonly root: string,
+        protected readonly run: CellRunner,
+        protected readonly env: NodeJS.ProcessEnv,
+        protected readonly log: (message: string) => void,
+    ) {}
+
+    async tools(): Promise<McpToolDefinition[]> {
+        const builtin = this.builtin();
+        const names = new Set(builtin.map(t => t.name));
+        return [...builtin, ...(await this.modules()).filter(t => !names.has(t.name))];
+    }
+
+    async close(): Promise<void> {
+        await this.toolchain?.close();
+        this.toolchain = undefined;
+    }
+
+    protected builtin(): McpToolDefinition[] {
+        const object = (properties: Record<string, unknown>, required: string[] = []) => ({
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+            additionalProperties: false,
+        });
+        const mode = { type: 'array', items: { type: 'string' }, description: 'Extra modes: each reads cell.<mode>.yml.' };
+        const preset = { type: 'string', description: 'Preset (default: cell.config.ts, CELL_PRESET, else node).' };
+        return [
+            {
+                name: 'info',
+                description:
+                    'The project model: preset, modes, targets, components, DI modules of each target, toolchain modules, hooks and the state of the output. Read-only and fast; start here.',
+                inputSchema: object({ preset, mode, appConfig: { type: 'boolean', description: 'Include the merged cell.yml of each target.' } }),
+                readOnly: true,
+                run: input => this.cell(['info', ...ProjectMcpTools.flags(input, { appConfig: 'app-config' })]),
+            },
+            {
+                name: 'check',
+                description:
+                    'Checks configuration, TypeScript types, decorator settings, DI bindings and module checks in one run. Every issue has a stable code, file, line and a fix hint; passed is false when an error-level issue is found.',
+                inputSchema: object({
+                    preset,
+                    mode,
+                    skip: { type: 'array', items: { type: 'string' }, description: 'Checks to skip: config, types, decorators, di or a module check.' },
+                }),
+                readOnly: true,
+                run: input => this.cell(['check', ...ProjectMcpTools.flags(input)], [0, 1]),
+            },
+            {
+                name: 'config_get',
+                description:
+                    'One value of the merged application configuration (cell*.yml of all components and modes, then CELL_<TARGET>__* variables) and the files and variables that set it. Backend values keep ${...}; the server evaluates them.',
+                inputSchema: object(
+                    {
+                        key: { type: 'string', description: 'Dotted key, e.g. cell.server.port.' },
+                        target: { type: 'string', enum: ['backend', 'frontend'], description: 'Default: backend, else frontend.' },
+                        mode,
+                    },
+                    ['key'],
+                ),
+                readOnly: true,
+                run: input => this.cell(['config', 'get', input.key as string, ...ProjectMcpTools.flags(input, {}, ['key'])]),
+            },
+            {
+                name: 'docs_search',
+                description:
+                    'Searches the docs (README.md, docs/) of the installed Cell components and toolchain modules, the versions this project uses. Returns the best matching sections with file and line.',
+                inputSchema: object(
+                    {
+                        query: { type: 'string', description: 'Words to look for, e.g. "transactional typeorm".' },
+                        limit: { type: 'integer', description: 'Sections to return (default 5).' },
+                    },
+                    ['query'],
+                ),
+                readOnly: true,
+                run: input => this.cell(['docs', input.query as string, ...ProjectMcpTools.flags(input, {}, ['query'])]),
+            },
+            {
+                name: 'build',
+                description:
+                    'Builds the application into the output directory (default .cell/output) as the preset prescribes, running build hooks. Writes files; no network.',
+                inputSchema: object({
+                    preset,
+                    mode,
+                    format: { type: 'string', enum: ['esm', 'cjs'], description: 'Server bundle format.' },
+                    sourcemap: { type: 'boolean' },
+                    outDir: { type: 'string', description: 'Output directory relative to the project root.' },
+                }),
+                readOnly: false,
+                run: input => this.cell(['build', ...ProjectMcpTools.flags(input, { outDir: 'out-dir' })]),
+            },
+            {
+                name: 'deploy_plan',
+                description:
+                    'What cell deploy would change on the platform of the preset (e.g. cloudflare), without deploying: builds (or reuses the output with skipBuild) and asks the deployer for a plan. Deploying itself is left to a person: cell deploy.',
+                inputSchema: object({
+                    preset,
+                    mode,
+                    skipBuild: { type: 'boolean', description: 'Plan the existing output instead of building.' },
+                    outDir: { type: 'string', description: 'Output directory relative to the project root.' },
+                }),
+                readOnly: false,
+                network: true,
+                run: input => this.cell(['deploy', '--dry-run', ...ProjectMcpTools.flags(input, { skipBuild: 'skip-build', outDir: 'out-dir' })]),
+            },
+        ];
+    }
+
+    /** Arguments as flags: arrays repeat, `true` is a bare flag, `false` and positional keys are left out. */
+    static flags(input: Record<string, unknown>, names: Record<string, string> = {}, skip: string[] = []): string[] {
+        return Object.entries(input).flatMap(([key, value]) => {
+            if (skip.includes(key) || value === undefined || value === false) {
+                return [];
+            }
+            const flag = `--${names[key] ?? key}`;
+            if (value === true) {
+                return [flag];
+            }
+            return (Array.isArray(value) ? value : [value]).flatMap(v => [flag, String(v)]);
+        });
+    }
+
+    /** Runs the command with `--json` and returns its result; a failure becomes the CellError it reported. */
+    protected async cell(argv: string[], success = [0]): Promise<Record<string, unknown>> {
+        const { code, stdout } = await this.run([...argv, '--root', this.root, '--json']);
+        let result: Record<string, unknown>;
+        try {
+            result = JSON.parse(stdout);
+        } catch (cause) {
+            throw new CellError({
+                code: 'CELL_INTERNAL_ERROR',
+                message: `cell ${argv[0]} printed no JSON result (exit code ${code}).`,
+                hint: 'Rerun the command in a terminal to see its output.',
+                cause,
+            });
+        }
+        if (!success.includes(code) || result.ok === false) {
+            const error = (result.error ?? {}) as { code?: string; message?: string; hint?: string; file?: string; line?: number; column?: number };
+            throw new CellError({
+                code: error.code ?? 'CELL_INTERNAL_ERROR',
+                message: error.message ?? `cell ${argv[0]} failed with exit code ${code}.`,
+                hint: error.hint,
+                file: error.file,
+                line: error.line,
+                column: error.column,
+            });
+        }
+        return result;
+    }
+
+    /** Tools of toolchain modules, from a toolchain loaded again when one of its files changed. */
+    protected async modules(): Promise<McpToolDefinition[]> {
+        const fingerprint = this.currentFingerprint();
+        if (this.toolchain && fingerprint === this.fingerprint) {
+            return this.moduleTools;
+        }
+        await this.close();
+        this.moduleTools = [];
+        try {
+            this.toolchain = await Toolchain.create({
+                root: this.root,
+                command: 'mcp',
+                env: this.env,
+                quiet: true,
+                runHooks: false,
+                logger: { info: m => this.log(m), warn: m => this.log(`warning: ${m}`) },
+            });
+        } catch (error) {
+            // The built-in tools still work and report the problem (info, check).
+            this.fingerprint = '';
+            this.log(`cell mcp: toolchain modules not loaded: ${(error as Error).message}`);
+            return [];
+        }
+        this.fingerprint = this.currentFingerprint();
+        const builtin = new Set(this.builtin().map(t => t.name));
+        for (const { source, value } of this.toolchain.modules.mcpTools) {
+            if (builtin.has(value.name) || this.moduleTools.some(t => t.name === value.name)) {
+                this.log(`warning: MCP tool '${value.name}' of ${source} is left out: the name is taken.`);
+                continue;
+            }
+            this.moduleTools.push(value);
+        }
+        return this.moduleTools;
+    }
+
+    /** Modification times of the files a toolchain is made of. */
+    protected currentFingerprint(): string {
+        const files = [
+            join(this.root, 'package.json'),
+            ...readdirSync(this.root)
+                .filter(name => /^cell\.config\.[cm]?[jt]s$/.test(name))
+                .map(name => join(this.root, name)),
+            ...(this.toolchain?.modules.loaded.map(m => resolve(this.root, m.file)) ?? []),
+        ];
+        return files.map(file => `${file}:${existsSync(file) ? statSync(file).mtimeMs : 0}`).join('|');
+    }
+}