@mrfentmen/openedge-abl-mcp 1.0.0 → 1.0.1

package/dist/core.js

@@ -1,301 +1,146 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { errorMessage, fail, run, text, ToolError } from "./run.js";
-const MAX_INPUT = 2_000_000;
-const DEFAULT_TIMEOUT = 30_000;
-const SKIP_DIRS = new Set([".git", ".mcp-build", "build", "dist", "node_modules", "vendor"]);
-function resolveDir(value) {
-    return path.resolve(value && value.length > 0 ? value : process.cwd());
-}
-function resolveFile(file, cwd) {
-    if (file.includes("\0"))
-        throw new ToolError("Path contains a null byte");
-    return path.isAbsolute(file) ? file : path.resolve(cwd, file);
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-async function fileExists(file) {
-    try {
-        await fs.stat(file);
-        return true;
-    }
-    catch {
-        return false;
+import { errorMessage, fail, text, ToolError } from "./run.js";
+const MAX_INPUT = 4_000_000;
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".mcp-build"]);
+async function readInput(input) {
+    if (input.path && input.content !== undefined)
+        throw new ToolError("Use path or content, not both");
+    if (input.content !== undefined) {
+        if (input.content.length > MAX_INPUT)
+            throw new ToolError(`Input is larger than ${MAX_INPUT} characters`);
+        return { body: input.content };
     }
-}
-async function readFileSafe(file) {
+    if (!input.path)
+        throw new ToolError("Provide a path or content");
+    if (input.path.includes("\0"))
+        throw new ToolError("Path contains a null byte");
+    const file = path.isAbsolute(input.path) ? input.path : path.resolve(input.cwd ? path.resolve(input.cwd) : process.cwd(), input.path);
     const stat = await fs.stat(file);
     if (!stat.isFile())
         throw new ToolError(`Not a file: ${file}`);
     if (stat.size > MAX_INPUT)
         throw new ToolError(`File is larger than ${MAX_INPUT} bytes`);
-    return fs.readFile(file, "utf8");
-}
-async function loadSource(input) {
-    const cwd = resolveDir(input.cwd);
-    if (input.path && input.content !== undefined) {
-        throw new ToolError("Use path or content, not both");
-    }
-    if (input.content !== undefined) {
-        return { content: input.content, cwd };
-    }
-    if (!input.path)
-        throw new ToolError("Provide a source path or content");
-    const file = resolveFile(input.path, cwd);
-    return { content: await readFileSafe(file), file, cwd: path.dirname(file) };
-}
-function commandContext(file, cwd, config) {
-    const ext = path.extname(file);
-    return {
-        file,
-        dir: cwd,
-        build: path.join(cwd, config.buildDir ?? ".mcp-build"),
-        stem: path.basename(file, ext),
-        ext,
-    };
-}
-function expandCommand(spec, ctx) {
-    const values = {
-        file: ctx.file,
-        dir: ctx.dir,
-        build: ctx.build,
-        stem: ctx.stem,
-        ext: ctx.ext,
-    };
-    const replace = (value) => value.replace(/\{(\w+)\}/g, (whole, key) => values[key] ?? whole);
-    return {
-        command: replace(spec.command),
-        args: spec.args.map(replace),
-        timeoutMs: spec.timeoutMs,
-    };
-}
-async function commandAvailable(command) {
-    const result = await run("which", [command], { timeoutMs: 5_000 });
-    return result.code === 0;
+    return { body: await fs.readFile(file, "utf8"), file };
 }
-async function runSteps(steps, ctx, cwd, timeoutMs) {
-    let output = "";
-    for (const step of steps) {
-        const expanded = expandCommand(step, ctx);
-        const result = await run(expanded.command, expanded.args, {
-            cwd,
-            timeoutMs: step.timeoutMs ?? timeoutMs,
-        });
-        output += result.stdout;
-        if (result.stderr.trim().length > 0) {
-            if (output.length > 0 && !output.endsWith("\n"))
-                output += "\n";
-            output += result.stderr;
-        }
-        if (result.code !== 0) {
-            throw new ToolError((result.stderr || result.stdout || `${expanded.command} exited with code ${result.code}`).trim());
-        }
+function parseOrThrow(format, body) {
+    const parsed = format.parse(body);
+    const errors = parsed.issues.filter((issue) => issue.severity === "error");
+    if (errors.length > 0) {
+        const first = errors.slice(0, 5).map((issue) => (issue.line ? `line ${issue.line}: ${issue.message}` : issue.message));
+        throw new ToolError(`${format.displayName} could not be parsed:\n${first.join("\n")}`);
     }
-    return output;
-}
-async function pickWorkflow(steps) {
-    if (steps.length === 0)
-        throw new ToolError("No command is configured");
-    if (await commandAvailable(steps[0].command))
-        return steps;
-    throw new ToolError(`${steps[0].command} is not installed or not on PATH. Install one of: ${[
-        ...new Set(steps.map((step) => step.command)),
-    ].join(", ")}`);
+    return parsed;
 }
-async function ensureBuildDir(ctx) {
-    await fs.mkdir(ctx.build, { recursive: true });
-}
-function scanStructure(content, config) {
-    const issues = [];
-    const stack = [];
-    const pairs = { ")": "(", "]": "[", "}": "{" };
-    const opens = new Set(["(", "[", "{"]);
-    const quotes = config.stringQuotes ?? ['"'];
-    let inString = null;
-    let stringLine = 0;
-    let escaped = false;
-    let line = 1;
-    for (let index = 0; index < content.length; index += 1) {
-        const char = content[index];
-        const rest = content.slice(index);
-        if (inString) {
-            if (escaped) {
-                escaped = false;
-            }
-            else if (char === "\\") {
-                escaped = true;
-            }
-            else if (char === inString) {
-                inString = null;
-            }
-            if (char === "\n")
-                line += 1;
-            continue;
-        }
-        if (config.blockComment && rest.startsWith(config.blockComment.start)) {
-            const end = content.indexOf(config.blockComment.end, index + config.blockComment.start.length);
-            if (end === -1) {
-                issues.push(`Line ${line}: unclosed block comment`);
-                break;
-            }
-            const skipped = content.slice(index, end + config.blockComment.end.length);
-            line += (skipped.match(/\n/g) ?? []).length;
-            index = end + config.blockComment.end.length - 1;
-            continue;
-        }
-        if (config.comment && rest.startsWith(config.comment)) {
-            const newline = content.indexOf("\n", index);
-            if (newline === -1)
-                break;
-            index = newline;
-            line += 1;
-            continue;
-        }
-        if (quotes.includes(char)) {
-            inString = char;
-            stringLine = line;
-            escaped = false;
-            continue;
-        }
-        if (char === "\n")
-            line += 1;
-        if (opens.has(char)) {
-            stack.push({ char, line });
-        }
-        else if (char in pairs) {
-            const open = stack.pop();
-            if (!open) {
-                issues.push(`Line ${line}: unexpected ${char}`);
+function numericStats(records) {
+    const out = {};
+    for (const record of records) {
+        for (const [key, value] of Object.entries(record.fields)) {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                continue;
+            const current = out[key];
+            if (!current) {
+                out[key] = { count: 1, min: value, max: value, mean: value, sum: value };
             }
-            else if (open.char !== pairs[char]) {
-                issues.push(`Line ${line}: ${char} closes ${open.char} from line ${open.line}`);
+            else {
+                current.count += 1;
+                current.sum += value;
+                current.min = Math.min(current.min, value);
+                current.max = Math.max(current.max, value);
+                current.mean = current.sum / current.count;
             }
         }
     }
-    if (inString)
-        issues.push(`Line ${stringLine}: unclosed string`);
-    for (const item of stack.slice(-5))
-        issues.push(`Line ${item.line}: unclosed ${item.char}`);
-    return issues;
-}
-function cleanFormat(content, expandTabs, indentWidth) {
-    const normalized = content.replace(/\r\n?/g, "\n");
-    const lines = normalized.split("\n").map((line) => {
-        const noTrailing = line.replace(/[ \t]+$/, "");
-        return expandTabs ? noTrailing.replace(/\t/g, " ".repeat(indentWidth)) : noTrailing;
-    });
-    const body = lines.join("\n").replace(/\n+$/, "");
-    return body.length > 0 ? `${body}\n` : "";
+    return out;
 }
-async function scanProject(dir, config, maxDepth) {
-    const scan = { files: 0, byExtension: {}, markers: {}, samples: [] };
-    const root = path.resolve(dir);
-    async function walk(current, depth) {
-        if (depth > maxDepth || scan.files >= 2_000)
-            return;
-        let entries;
-        try {
-            entries = await fs.readdir(current, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            if (entry.name.startsWith(".") && entry.name !== ".env")
-                continue;
-            const full = path.join(current, entry.name);
-            if (entry.isDirectory()) {
-                if (SKIP_DIRS.has(entry.name))
-                    continue;
-                await walk(full, depth + 1);
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            const ext = path.extname(entry.name).toLowerCase();
-            const isMarker = config.markers.includes(entry.name);
-            if (!config.extensions.includes(ext) && !isMarker)
-                continue;
-            scan.files += 1;
-            if (ext)
-                scan.byExtension[ext] = (scan.byExtension[ext] ?? 0) + 1;
-            if (isMarker)
-                scan.markers[entry.name] = (scan.markers[entry.name] ?? 0) + 1;
-            if (scan.samples.length < 20)
-                scan.samples.push(path.relative(root, full));
-            if (scan.files >= 2_000)
-                return;
-        }
-    }
-    await walk(root, 0);
-    return scan;
+function round(value) {
+    return Number.isFinite(value) ? Math.round(value * 1000) / 1000 : value;
 }
-export function registerLanguageTools(server, config) {
+export function registerFormatTools(server, format) {
     const sourceArgs = {
         path: z.string().min(1).max(2_000).optional(),
         content: z.string().max(MAX_INPUT).optional(),
         cwd: z.string().min(1).max(2_000).optional(),
     };
-    const timeout = z.number().int().min(1_000).max(120_000).default(DEFAULT_TIMEOUT);
-    server.tool("detect_project", `Find ${config.displayName} files, project markers and the toolchain layout in a directory.`, {
+    server.tool("detect_files", `Find ${format.displayName} files (${format.extensions.join(", ")}) in a directory tree.`, {
         path: z.string().min(1).max(2_000).default("."),
-        maxDepth: z.number().int().min(0).max(8).default(3),
+        maxDepth: z.number().int().min(0).max(8).default(4),
     }, async (a) => {
         try {
-            const root = resolveDir(a.path);
+            const root = path.resolve(a.path);
             const stat = await fs.stat(root);
             if (!stat.isDirectory())
                 throw new ToolError(`Not a directory: ${root}`);
-            const scan = await scanProject(root, config, a.maxDepth);
-            return text(JSON.stringify({
-                language: config.displayName,
-                root,
-                extensions: config.extensions,
-                markers: config.markers,
-                files: scan.files,
-                byExtension: scan.byExtension,
-                markerFiles: scan.markers,
-                samples: scan.samples,
-            }, null, 2));
+            const found = [];
+            let scanned = 0;
+            async function walk(dir, depth) {
+                if (depth > a.maxDepth || found.length >= 500)
+                    return;
+                let entries;
+                try {
+                    entries = await fs.readdir(dir, { withFileTypes: true });
+                }
+                catch {
+                    return;
+                }
+                for (const entry of entries) {
+                    if (entry.name.startsWith("."))
+                        continue;
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        if (SKIP_DIRS.has(entry.name))
+                            continue;
+                        await walk(full, depth + 1);
+                        continue;
+                    }
+                    if (!entry.isFile())
+                        continue;
+                    scanned += 1;
+                    if (!format.extensions.includes(path.extname(entry.name).toLowerCase()))
+                        continue;
+                    found.push(path.relative(root, full));
+                    if (found.length >= 500)
+                        return;
+                }
+            }
+            await walk(root, 0);
+            return text(JSON.stringify({ format: format.displayName, root, filesScanned: scanned, matches: found.length, files: found }, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("read_source", `Read a ${config.displayName} source file, optionally a line range.`, {
+    server.tool("read_file", `Read a ${format.displayName} file, optionally a line range.`, {
         path: z.string().min(1).max(2_000),
         startLine: z.number().int().min(1).default(1),
         endLine: z.number().int().min(1).optional(),
         cwd: z.string().min(1).max(2_000).optional(),
     }, async (a) => {
         try {
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            const content = await readFileSafe(file);
-            const lines = content.split("\n");
+            const { body } = await readInput({ path: a.path, cwd: a.cwd });
+            const lines = body.split(/\r?\n/);
             const end = Math.min(a.endLine ?? lines.length, lines.length);
-            const body = lines.slice(a.startLine - 1, end).join("\n");
-            return text(body);
+            return text(lines.slice(a.startLine - 1, end).join("\n"));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("write_source", `Write a ${config.displayName} source file. Refuses to overwrite unless overwrite is true.`, {
+    server.tool("write_file", `Write a ${format.displayName} file. Refuses to overwrite unless overwrite is true.`, {
         path: z.string().min(1).max(2_000),
         content: z.string().max(MAX_INPUT),
         overwrite: z.boolean().default(false),
-        createDirs: z.boolean().default(true),
         cwd: z.string().min(1).max(2_000).optional(),
     }, async (a) => {
         try {
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            if (!a.overwrite && (await fileExists(file))) {
-                throw new ToolError(`File already exists: ${file}. Set overwrite=true to replace it.`);
+            const file = path.isAbsolute(a.path) ? a.path : path.resolve(a.cwd ? path.resolve(a.cwd) : process.cwd(), a.path);
+            if (!a.overwrite) {
+                const exists = await fs.stat(file).then(() => true).catch(() => false);
+                if (exists)
+                    throw new ToolError(`File already exists: ${file}. Set overwrite=true to replace it.`);
             }
-            if (a.createDirs)
-                await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.mkdir(path.dirname(file), { recursive: true });
             await fs.writeFile(file, a.content, "utf8");
             return text(`Wrote ${Buffer.byteLength(a.content)} bytes to ${file}`);
         }
@@ -303,400 +148,196 @@ export function registerLanguageTools(server, config) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("syntax_check", `Check ${config.displayName} structure and, when configured, run the real parser without executing the program.`, {
-        ...sourceArgs,
-    }, async (a) => {
-        try {
-            const source = await loadSource(a);
-            const issues = scanStructure(source.content, config);
-            let parserChecked = false;
-            if (config.syntax && source.file) {
-                const ctx = commandContext(source.file, source.cwd, config);
-                const command = expandCommand(config.syntax, ctx);
-                const result = await run(command.command, command.args, {
-                    cwd: source.cwd,
-                    timeoutMs: DEFAULT_TIMEOUT,
-                });
-                parserChecked = result.code === 0;
-                if (result.code !== 0) {
-                    issues.push((result.stderr || result.stdout || "parser rejected the file").trim());
-                }
-            }
-            if (issues.length > 0)
-                throw new ToolError(issues.join("\n"));
-            return text(parserChecked ? "Syntax OK (parser accepted the file)" : "Syntax OK (structure check)");
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("format_source", `Trim trailing whitespace, normalize line endings and ensure a final newline in ${config.displayName} code.`, {
-        ...sourceArgs,
-        expandTabs: z.boolean().default(false),
-        indentWidth: z.number().int().min(2).max(8).default(2),
-        write: z.boolean().default(false),
-    }, async (a) => {
+    server.tool("parse", `Parse ${format.displayName} into records, fields and document metadata.`, { ...sourceArgs }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const formatted = cleanFormat(source.content, a.expandTabs, a.indentWidth);
-            if (a.write && source.file) {
-                await fs.writeFile(source.file, formatted, "utf8");
-                return text(`Formatted ${source.file}`);
-            }
-            return text(formatted);
+            const { body, file } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            return text(JSON.stringify({
+                file: file ?? null,
+                format: parsed.format,
+                meta: parsed.meta,
+                records: parsed.records.length,
+                kinds: parsed.records.reduce((acc, record) => {
+                    acc[record.kind] = (acc[record.kind] ?? 0) + 1;
+                    return acc;
+                }, {}),
+                issues: parsed.issues,
+            }, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("lint_source", `Check ${config.displayName} code for trailing whitespace, tabs, long lines, missing final newline and unbalanced structure.`, {
-        ...sourceArgs,
-        maxLineLength: z.number().int().min(40).max(400).default(120),
-    }, async (a) => {
+    server.tool("validate", `Validate ${format.displayName} against its structural rules and report every issue with a line number.`, { ...sourceArgs }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const issues = [];
-            const lines = source.content.replace(/\r\n?/g, "\n").split("\n");
-            lines.forEach((line, index) => {
-                if (/[ \t]+$/.test(line))
-                    issues.push(`Line ${index + 1}: trailing whitespace`);
-                if (!config.allowTabs && line.includes("\t"))
-                    issues.push(`Line ${index + 1}: tab character`);
-                if (line.length > a.maxLineLength) {
-                    issues.push(`Line ${index + 1}: ${line.length} characters (max ${a.maxLineLength})`);
-                }
-            });
-            if (source.content.length > 0 && !source.content.endsWith("\n")) {
-                issues.push("File does not end with a newline");
-            }
-            issues.push(...scanStructure(source.content, config));
-            if (issues.length === 0)
-                return text("No lint issues");
-            return text(issues.join("\n"));
+            const { body } = await readInput(a);
+            const parsed = format.parse(body);
+            const errors = parsed.issues.filter((issue) => issue.severity === "error").length;
+            const warnings = parsed.issues.length - errors;
+            return text(JSON.stringify({
+                format: parsed.format,
+                valid: errors === 0,
+                errors,
+                warnings,
+                issues: parsed.issues,
+            }, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("extract_symbols", `List functions, classes, types and other ${config.displayName} definitions with line numbers.`, {
-        ...sourceArgs,
-    }, async (a) => {
+    server.tool("summarize", `Summarize a ${format.displayName} document: metadata, record counts and per-kind totals.`, { ...sourceArgs }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const found = [];
-            const lines = source.content.split("\n");
-            for (const rule of config.symbols) {
-                const regex = new RegExp(rule.pattern, rule.flags ?? "i");
-                lines.forEach((line, index) => {
-                    const match = regex.exec(line);
-                    if (match)
-                        found.push(`Line ${index + 1}: ${rule.kind} ${match[1] ?? match[0]}`);
-                });
-            }
-            return text(found.length > 0 ? found.join("\n") : "No symbols found");
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const kinds = parsed.records.reduce((acc, record) => {
+                acc[record.kind] = (acc[record.kind] ?? 0) + 1;
+                return acc;
+            }, {});
+            const lines = [
+                `${format.displayName} document`,
+                `records: ${parsed.records.length}`,
+                ...Object.entries(kinds).map(([kind, count]) => `  ${kind}: ${count}`),
+                ...Object.entries(parsed.meta).map(([key, value]) => `${key}: ${String(value)}`),
+                `issues: ${parsed.issues.length}`,
+            ];
+            return text(lines.join("\n"));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("list_imports", `List imports, includes and dependencies in a ${config.displayName} source file.`, {
+    server.tool("list_records", `List ${format.displayName} record ids and kinds, with a limit.`, {
         ...sourceArgs,
+        limit: z.number().int().min(1).max(1_000).default(50),
     }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const found = [];
-            const lines = source.content.split("\n");
-            for (const rule of config.imports) {
-                const regex = new RegExp(rule.pattern, rule.flags ?? "i");
-                lines.forEach((line, index) => {
-                    const match = regex.exec(line);
-                    if (match)
-                        found.push(`Line ${index + 1}: ${rule.kind} ${match[1] ?? match[0]}`);
-                });
-            }
-            return text(found.length > 0 ? found.join("\n") : "No imports found");
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const rows = parsed.records.slice(0, a.limit).map((record) => `${record.kind}\t${record.id}`);
+            const rest = parsed.records.length - rows.length;
+            return text(rows.join("\n") + (rest > 0 ? `\n... ${rest} more` : ""));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("list_todos", `Find TODO, FIXME, HACK and XXX comments in ${config.displayName} code.`, {
+    server.tool("get_record", `Return one ${format.displayName} record by id, with all parsed fields.`, {
         ...sourceArgs,
+        id: z.string().min(1).max(300),
     }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const found = [];
-            source.content.split("\n").forEach((line, index) => {
-                if (/\b(TODO|FIXME|HACK|XXX)\b/i.test(line))
-                    found.push(`Line ${index + 1}: ${line.trim()}`);
-            });
-            return text(found.length > 0 ? found.join("\n") : "No TODO comments found");
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("find_references", `Find every mention of a symbol in one ${config.displayName} source file.`, {
-        path: z.string().min(1).max(2_000),
-        symbol: z.string().min(1).max(200),
-        cwd: z.string().min(1).max(2_000).optional(),
-    }, async (a) => {
-        try {
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            const content = await readFileSafe(file);
-            const regex = new RegExp(`(?<![A-Za-z0-9_])${escapeRegExp(a.symbol)}(?![A-Za-z0-9_])`, "g");
-            const found = [];
-            content.split("\n").forEach((line, index) => {
-                const count = [...line.matchAll(regex)].length;
-                if (count > 0)
-                    found.push(`Line ${index + 1}: ${count} reference(s)`);
-            });
-            return text(found.length > 0 ? found.join("\n") : `No references to ${a.symbol}`);
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("rename_symbol", `Rename one symbol in a ${config.displayName} file. Defaults to a dry run.`, {
-        path: z.string().min(1).max(2_000),
-        oldName: z.string().min(1).max(200),
-        newName: z.string().min(1).max(200),
-        dryRun: z.boolean().default(true),
-        cwd: z.string().min(1).max(2_000).optional(),
-    }, async (a) => {
-        try {
-            if (/[\r\n]/.test(a.newName))
-                throw new ToolError("New name cannot contain a newline");
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            const content = await readFileSafe(file);
-            const regex = new RegExp(`(?<![A-Za-z0-9_])${escapeRegExp(a.oldName)}(?![A-Za-z0-9_])`, "g");
-            const count = [...content.matchAll(regex)].length;
-            if (count === 0)
-                return text(`No references to ${a.oldName}`);
-            if (a.dryRun)
-                return text(`Dry run: would replace ${count} occurrence(s) in ${file}`);
-            await fs.writeFile(file, content.replace(regex, () => a.newName), "utf8");
-            return text(`Renamed ${count} occurrence(s) in ${file}`);
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("insert_snippet", `Insert a real ${config.displayName} starter snippet into a file. Defaults to a dry run.`, {
-        path: z.string().min(1).max(2_000),
-        snippet: z.string().min(1).max(80),
-        line: z.number().int().min(1).optional(),
-        dryRun: z.boolean().default(true),
-        cwd: z.string().min(1).max(2_000).optional(),
-    }, async (a) => {
-        try {
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            const snippet = config.snippets[a.snippet];
-            if (!snippet) {
-                throw new ToolError(`Unknown snippet: ${a.snippet}. Available: ${Object.entries(config.snippets)
-                    .map(([key, value]) => `${key} (${value.description})`)
-                    .join(", ")}`);
-            }
-            const content = await readFileSafe(file);
-            const lines = content.split("\n");
-            const index = a.line ? Math.min(a.line - 1, lines.length) : lines.length;
-            lines.splice(index, 0, ...snippet.body.split("\n"));
-            const next = lines.join("\n");
-            if (a.dryRun) {
-                return text(`Dry run: would insert ${a.snippet} at line ${index + 1} in ${file}`);
-            }
-            await fs.writeFile(file, next, "utf8");
-            return text(`Inserted ${a.snippet} at line ${index + 1} in ${file}`);
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const record = parsed.records.find((item) => item.id === a.id);
+            if (!record)
+                throw new ToolError(`No record with id ${a.id}. Use list_records to see available ids.`);
+            return text(JSON.stringify(record, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("comment_lines", `Comment a line range in ${config.displayName} code using the language comment marker.`, {
+    server.tool("search", `Search ${format.displayName} records by plain text or regular expression.`, {
         ...sourceArgs,
-        startLine: z.number().int().min(1).default(1),
-        endLine: z.number().int().min(1).optional(),
-        write: z.boolean().default(false),
+        query: z.string().min(1).max(500),
+        regex: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(50),
     }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const lines = source.content.split("\n");
-            const end = Math.min(a.endLine ?? lines.length, lines.length);
-            let changed = 0;
-            for (let index = a.startLine - 1; index < end; index += 1) {
-                if (lines[index].trim().length > 0 && !lines[index].trimStart().startsWith(config.comment)) {
-                    const indent = lines[index].slice(0, lines[index].length - lines[index].trimStart().length);
-                    lines[index] = `${indent}${config.comment} ${lines[index].slice(indent.length)}`;
-                    changed += 1;
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            let test;
+            if (a.regex) {
+                let pattern;
+                try {
+                    pattern = new RegExp(a.query, "i");
+                }
+                catch {
+                    throw new ToolError(`Invalid regular expression: ${a.query}`);
                 }
+                test = (value) => pattern.test(value);
             }
-            const next = lines.join("\n");
-            if (a.write && source.file) {
-                await fs.writeFile(source.file, next, "utf8");
-                return text(`Commented ${changed} line(s) in ${source.file}`);
+            else {
+                const needle = a.query.toLowerCase();
+                test = (value) => value.toLowerCase().includes(needle);
             }
-            return text(next);
+            const matches = parsed.records.filter((record) => test(`${record.id} ${record.kind} ${JSON.stringify(record.fields)}`));
+            const rows = matches.slice(0, a.limit).map((record) => `${record.kind}\t${record.id}`);
+            return text(`${matches.length} match(es)\n${rows.join("\n")}`.trim());
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("uncomment_lines", `Remove the ${config.displayName} comment marker from a line range.`, {
+    server.tool("stats", `Numeric statistics for ${format.displayName} fields across all records.`, {
         ...sourceArgs,
-        startLine: z.number().int().min(1).default(1),
-        endLine: z.number().int().min(1).optional(),
-        write: z.boolean().default(false),
+        field: z.string().min(1).max(120).optional(),
     }, async (a) => {
         try {
-            const source = await loadSource(a);
-            const lines = source.content.split("\n");
-            const end = Math.min(a.endLine ?? lines.length, lines.length);
-            let changed = 0;
-            for (let index = a.startLine - 1; index < end; index += 1) {
-                const match = lines[index].match(/^(\s*)(.*)$/);
-                if (!match)
-                    continue;
-                const indent = match[1];
-                const rest = match[2];
-                if (!rest.startsWith(config.comment))
-                    continue;
-                const after = rest.slice(config.comment.length);
-                lines[index] = `${indent}${after.startsWith(" ") ? after.slice(1) : after}`;
-                changed += 1;
+            const { body } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            const stats = numericStats(parsed.records);
+            if (a.field) {
+                const one = stats[a.field];
+                if (!one)
+                    throw new ToolError(`Field ${a.field} has no numeric values. Numeric fields: ${Object.keys(stats).join(", ") || "none"}`);
+                return text(JSON.stringify({ [a.field]: { ...one, mean: round(one.mean) } }, null, 2));
             }
-            const next = lines.join("\n");
-            if (a.write && source.file) {
-                await fs.writeFile(source.file, next, "utf8");
-                return text(`Uncommented ${changed} line(s) in ${source.file}`);
-            }
-            return text(next);
+            const rounded = Object.fromEntries(Object.entries(stats).map(([key, value]) => [key, { ...value, mean: round(value.mean) }]));
+            return text(JSON.stringify(rounded, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("scaffold_project", `Create a small runnable ${config.displayName} project with a starter file and test directory.`, {
-        path: z.string().min(1).max(2_000).default("."),
-        projectName: z.string().min(1).max(120).optional(),
-        overwrite: z.boolean().default(false),
-    }, async (a) => {
+    server.tool("to_json", `Export every parsed ${format.displayName} record as JSON.`, { ...sourceArgs }, async (a) => {
         try {
-            const root = resolveDir(a.path);
-            const name = a.projectName ?? config.slug;
-            if (!/^[A-Za-z0-9_.-]+$/.test(name))
-                throw new ToolError("Invalid project name");
-            const created = [];
-            for (const file of config.scaffold) {
-                const relative = file.path.replace(/\{\{name\}\}/g, name);
-                const normalized = path.normalize(relative);
-                if (path.isAbsolute(normalized) || normalized.startsWith("..")) {
-                    throw new ToolError(`Unsafe scaffold path: ${relative}`);
-                }
-                const target = path.join(root, normalized);
-                if (!a.overwrite && (await fileExists(target))) {
-                    throw new ToolError(`File already exists: ${target}`);
-                }
-                await fs.mkdir(path.dirname(target), { recursive: true });
-                await fs.writeFile(target, file.content.replace(/\{\{name\}\}/g, name), "utf8");
-                created.push(normalized);
-            }
-            return text(`Created ${created.length} file(s):\n${created.join("\n")}`);
+            const { body, file } = await readInput(a);
+            const parsed = parseOrThrow(format, body);
+            return text(JSON.stringify({
+                file: file ?? null,
+                format: parsed.format,
+                meta: parsed.meta,
+                issues: parsed.issues,
+                records: parsed.records,
+            }, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("run_source", `Run a ${config.displayName} file with the installed interpreter or compiler.`, {
-        path: z.string().min(1).max(2_000),
+    server.tool("diff", `Compare two ${format.displayName} documents: added, removed and changed records.`, {
+        leftPath: z.string().min(1).max(2_000).optional(),
+        leftContent: z.string().max(MAX_INPUT).optional(),
+        rightPath: z.string().min(1).max(2_000).optional(),
+        rightContent: z.string().max(MAX_INPUT).optional(),
         cwd: z.string().min(1).max(2_000).optional(),
-        timeoutMs: timeout,
-    }, async (a) => {
-        try {
-            if (!config.runner || config.runner.length === 0) {
-                throw new ToolError(`No runner is configured for ${config.displayName}`);
-            }
-            const file = resolveFile(a.path, resolveDir(a.cwd));
-            const cwd = path.dirname(file);
-            const ctx = commandContext(file, cwd, config);
-            await ensureBuildDir(ctx);
-            const workflow = await pickWorkflow(config.runner);
-            const output = await runSteps(workflow, ctx, cwd, a.timeoutMs);
-            return text(output.trim().length > 0 ? output : "(no output)");
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("run_tests", `Run the configured ${config.displayName} test command in a project directory.`, {
-        cwd: z.string().min(1).max(2_000).default("."),
-        timeoutMs: timeout,
-    }, async (a) => {
-        try {
-            if (!config.test || config.test.length === 0) {
-                throw new ToolError(`No test command is configured for ${config.displayName}`);
-            }
-            const cwd = resolveDir(a.cwd);
-            const ctx = commandContext(path.join(cwd, config.slug), cwd, config);
-            await ensureBuildDir(ctx);
-            const output = await runSteps(config.test, ctx, cwd, a.timeoutMs);
-            return text(output.trim().length > 0 ? output : "Tests passed");
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("build_project", `Build a ${config.displayName} project with the configured compiler command.`, {
-        cwd: z.string().min(1).max(2_000).default("."),
-        path: z.string().min(1).max(2_000).optional(),
-        timeoutMs: timeout,
     }, async (a) => {
         try {
-            if (!config.build || config.build.length === 0) {
-                throw new ToolError(`No build step is configured for ${config.displayName}`);
-            }
-            const cwd = resolveDir(a.cwd);
-            let file = a.path ? resolveFile(a.path, cwd) : "";
-            if (!file) {
-                const scan = await scanProject(cwd, config, 3);
-                const first = scan.samples.find((sample) => config.extensions.includes(path.extname(sample).toLowerCase()));
-                if (first)
-                    file = path.join(cwd, first);
-            }
-            const ctx = commandContext(file || path.join(cwd, config.slug), cwd, config);
-            await ensureBuildDir(ctx);
-            const output = await runSteps(config.build, ctx, cwd, a.timeoutMs);
-            return text(output.trim().length > 0 ? output : "Build passed");
-        }
-        catch (error) {
-            return fail(errorMessage(error));
-        }
-    });
-    server.tool("toolchain_status", `Show which ${config.displayName} compilers, interpreters, build tools and test commands are installed.`, {}, async () => {
-        try {
-            const commands = new Set();
-            for (const step of [
-                ...(config.runner ?? []),
-                ...(config.syntax ? [config.syntax] : []),
-                ...(config.build ?? []),
-                ...(config.test ?? []),
-            ]) {
-                commands.add(step.command);
-            }
-            const lines = [];
-            for (const command of [...commands].sort()) {
-                if (!(await commandAvailable(command))) {
-                    lines.push(`${command}: not found`);
-                    continue;
-                }
-                const version = await run(command, ["--version"], { timeoutMs: 5_000 });
-                const first = (version.stdout || version.stderr).split("\n").find((line) => line.trim().length > 0);
-                lines.push(`${command}: ${first?.trim() ?? "installed"}`);
-            }
-            return text(lines.join("\n") || "No toolchain commands configured");
+            const left = await readInput({ path: a.leftPath, content: a.leftContent, cwd: a.cwd });
+            const right = await readInput({ path: a.rightPath, content: a.rightContent, cwd: a.cwd });
+            const before = parseOrThrow(format, left.body);
+            const after = parseOrThrow(format, right.body);
+            const beforeFields = new Map(before.records.map((record) => [record.id, JSON.stringify(record.fields)]));
+            const afterFields = new Map(after.records.map((record) => [record.id, JSON.stringify(record.fields)]));
+            const added = [...afterFields.keys()].filter((id) => !beforeFields.has(id));
+            const removed = [...beforeFields.keys()].filter((id) => !afterFields.has(id));
+            const changed = [...afterFields.keys()].filter((id) => beforeFields.has(id) && beforeFields.get(id) !== afterFields.get(id));
+            return text(JSON.stringify({
+                format: before.format,
+                added: added.length,
+                removed: removed.length,
+                changed: changed.length,
+                unchanged: afterFields.size - added.length - changed.length,
+                records: { added, removed, changed },
+                issues: { left: before.issues.length, right: after.issues.length },
+            }, null, 2));
         }
         catch (error) {
             return fail(errorMessage(error));
         }
     });
-    server.tool("language_reference", `Return a compact ${config.displayName} syntax and toolchain reference for agents.`, {}, async () => text(config.reference));
+    server.tool("format_reference", `Return a compact ${format.displayName} reference: structure, required fields and common pitfalls.`, {}, async () => text(format.reference));
+    server.tool("sample", `Return a small but valid ${format.displayName} example document.`, {}, async () => text(format.sample()));
 }