mdkg 0.3.4 → 0.3.6

package/dist/commands/mcp.js

@@ -0,0 +1,647 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleMcpRequest = handleMcpRequest;
+exports.handleMcpMessage = handleMcpMessage;
+exports.runMcpServeCommand = runMcpServeCommand;
+const readline_1 = __importDefault(require("readline"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const status_1 = require("./status");
+const validate_1 = require("./validate");
+const config_1 = require("../core/config");
+const version_1 = require("../core/version");
+const index_cache_1 = require("../graph/index_cache");
+const node_body_1 = require("../graph/node_body");
+const goal_scope_1 = require("../graph/goal_scope");
+const node_1 = require("../graph/node");
+const headings_1 = require("../templates/headings");
+const pack_1 = require("../pack/pack");
+const budget_1 = require("../pack/budget");
+const profile_1 = require("../pack/profile");
+const filter_1 = require("../util/filter");
+const errors_1 = require("../util/errors");
+const qid_1 = require("../util/qid");
+const sort_1 = require("../util/sort");
+const query_output_1 = require("./query_output");
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const SERVER_NAME = "mdkg";
+const MAX_SEARCH_LIMIT = 100;
+const DEFAULT_SEARCH_LIMIT = 20;
+const MAX_PACK_NODES = 100;
+const DEFAULT_PACK_NODES = 20;
+const DEFAULT_PACK_MAX_CHARS = 120000;
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties,
+        required,
+    };
+}
+const stringProp = (description) => ({ type: "string", description });
+const numberProp = (description) => ({ type: "integer", description });
+const booleanProp = (description) => ({ type: "boolean", description });
+const MCP_TOOLS = [
+    {
+        name: "mdkg_status",
+        title: "mdkg status",
+        description: "Return read-only mdkg operator status for the selected root.",
+        inputSchema: objectSchema({}),
+    },
+    {
+        name: "mdkg_workspace_list",
+        title: "mdkg workspace list",
+        description: "List root workspaces and configured read-only subgraph aliases.",
+        inputSchema: objectSchema({}),
+    },
+    {
+        name: "mdkg_search",
+        title: "mdkg search",
+        description: "Search mdkg graph metadata across local and read-only subgraph indexes.",
+        inputSchema: objectSchema({
+            query: stringProp("Search query."),
+            ws: stringProp("Optional workspace or subgraph alias."),
+            type: stringProp("Optional node type filter."),
+            status: stringProp("Optional node status filter."),
+            limit: numberProp("Maximum result count, capped at 100."),
+        }, ["query"]),
+    },
+    {
+        name: "mdkg_show",
+        title: "mdkg show",
+        description: "Show one mdkg node by local id, qid, or subgraph qid.",
+        inputSchema: objectSchema({
+            id: stringProp("Node id or qid."),
+            ws: stringProp("Optional workspace or subgraph alias hint."),
+            meta_only: booleanProp("Return metadata without Markdown body."),
+        }, ["id"]),
+    },
+    {
+        name: "mdkg_pack",
+        title: "mdkg pack",
+        description: "Build a bounded in-memory context pack without writing .mdkg/pack files.",
+        inputSchema: objectSchema({
+            id: stringProp("Pack root id or qid."),
+            ws: stringProp("Optional workspace or subgraph alias hint."),
+            profile: stringProp("Pack profile: standard, concise, or headers. Defaults to concise."),
+            max_nodes: numberProp("Maximum node count, capped at 100."),
+            max_chars: numberProp("Maximum estimated character budget. Defaults to 120000."),
+        }, ["id"]),
+    },
+    {
+        name: "mdkg_goal_current",
+        title: "mdkg goal current",
+        description: "Return the selected local goal or the unique active local root goal fallback.",
+        inputSchema: objectSchema({ ws: stringProp("Optional local workspace alias.") }),
+    },
+    {
+        name: "mdkg_goal_next",
+        title: "mdkg goal next",
+        description: "Return the next actionable local node inside a goal scope without mutating active_node.",
+        inputSchema: objectSchema({
+            id: stringProp("Optional goal id or qid. Defaults to selected or unique active goal."),
+            ws: stringProp("Optional local workspace alias."),
+        }),
+    },
+    {
+        name: "mdkg_validate",
+        title: "mdkg validate",
+        description: "Return the read-only validation receipt for the selected root.",
+        inputSchema: objectSchema({}),
+    },
+];
+function toolDescription(tool) {
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    };
+}
+function asObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new errors_1.UsageError(`${key} is required and must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new errors_1.UsageError(`${key} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalBoolean(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new errors_1.UsageError(`${key} must be a boolean`);
+    }
+    return value;
+}
+function optionalInteger(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new errors_1.UsageError(`${key} must be an integer`);
+    }
+    return value;
+}
+function clampLimit(raw, fallback, max) {
+    if (raw === undefined) {
+        return fallback;
+    }
+    if (raw < 1) {
+        throw new errors_1.UsageError("limit values must be positive integers");
+    }
+    return Math.min(raw, max);
+}
+function normalizeWorkspace(value) {
+    if (!value || value === "all") {
+        return undefined;
+    }
+    return value.toLowerCase();
+}
+function loadReadOnlyIndex(root) {
+    const config = (0, config_1.loadConfig)(root);
+    const { index } = (0, index_cache_1.loadIndex)({
+        root,
+        config,
+        useCache: false,
+        allowReindex: false,
+        includeImports: true,
+    });
+    return { config, index };
+}
+function ensureKnownWorkspace(config, ws) {
+    if (!ws) {
+        return undefined;
+    }
+    if (!config.workspaces[ws] && !config.subgraphs[ws]) {
+        throw new errors_1.NotFoundError(`workspace or subgraph not found: ${ws}`);
+    }
+    return ws;
+}
+function buildSearchText(node) {
+    const attributeTokens = Object.entries(node.attributes ?? {}).flatMap(([key, value]) => {
+        if (Array.isArray(value)) {
+            return [key, ...value.map((item) => String(item))];
+        }
+        return [key, String(value)];
+    });
+    return [
+        node.id,
+        node.qid,
+        node.type,
+        node.title,
+        node.path,
+        ...node.tags,
+        ...node.owners,
+        ...node.links,
+        ...node.artifacts,
+        ...node.refs,
+        ...node.aliases,
+        ...node.skills,
+        ...attributeTokens,
+    ]
+        .join(" ")
+        .toLowerCase();
+}
+function matchesSearch(node, terms) {
+    const haystack = buildSearchText(node);
+    return terms.every((term) => haystack.includes(term));
+}
+function selectedGoalState(root) {
+    const filePath = path_1.default.join(root, ".mdkg", "state", "selected-goal.json");
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+        if (typeof parsed.qid === "string" &&
+            typeof parsed.id === "string" &&
+            typeof parsed.ws === "string" &&
+            typeof parsed.selected_at === "string") {
+            return {
+                qid: parsed.qid.toLowerCase(),
+                id: parsed.id.toLowerCase(),
+                ws: parsed.ws.toLowerCase(),
+                selected_at: parsed.selected_at,
+            };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function activeGoalCandidates(index, ws) {
+    return Object.values(index.nodes)
+        .filter((node) => node.type === "goal")
+        .filter((node) => !node.source?.imported)
+        .filter((node) => (ws ? node.ws === ws : true))
+        .filter((node) => node.status === "progress" && node.attributes.goal_state === "active")
+        .sort((a, b) => a.qid.localeCompare(b.qid));
+}
+function isArchivedGoal(node) {
+    return Boolean(node &&
+        node.type === "goal" &&
+        (node.status === "archived" || node.attributes.goal_state === "archived"));
+}
+function resolveGoal(root, index, idOrQid, ws) {
+    const warnings = [];
+    if (idOrQid) {
+        const resolved = (0, qid_1.resolveQid)(index, idOrQid, ws);
+        if (resolved.status !== "ok") {
+            throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("goal", idOrQid, resolved, ws));
+        }
+        const node = index.nodes[resolved.qid];
+        if (!node || node.type !== "goal") {
+            throw new errors_1.UsageError(`mdkg_goal_next requires a goal node; got ${idOrQid}`);
+        }
+        return { source: "explicit", node, warnings };
+    }
+    const selected = selectedGoalState(root);
+    if (selected) {
+        const node = index.nodes[selected.qid];
+        if (node && (!ws || node.ws === ws)) {
+            return { source: "selected", node, warnings };
+        }
+        warnings.push("selected goal is missing or outside the requested workspace");
+    }
+    const active = activeGoalCandidates(index, ws);
+    if (active.length === 1) {
+        return { source: "unique_active", node: active[0], warnings };
+    }
+    if (active.length > 1) {
+        throw new errors_1.UsageError(`multiple active local goals found: ${active.map((node) => node.qid).join(", ")}`);
+    }
+    throw new errors_1.NotFoundError("no selected or active local goal found");
+}
+function isConcreteGoalCandidate(node, statusRanks) {
+    if (node.source?.imported) {
+        return false;
+    }
+    if (!goal_scope_1.GOAL_SCOPE_ACTIONABLE_TYPES.has(node.type)) {
+        return false;
+    }
+    if (!node.status || !statusRanks.has(node.status)) {
+        return false;
+    }
+    return node.status !== "done" && node.status !== "archived";
+}
+function toolResult(payload, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+        structuredContent: payload,
+        isError,
+    };
+}
+function listWorkspaces(root) {
+    const config = (0, config_1.loadConfig)(root);
+    return {
+        action: "mcp.workspace_list",
+        root,
+        workspaces: Object.entries(config.workspaces)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([alias, entry]) => ({
+            alias,
+            path: entry.path,
+            mdkg_dir: entry.mdkg_dir,
+            enabled: entry.enabled,
+            visibility: entry.visibility,
+        })),
+        subgraphs: Object.entries(config.subgraphs)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([alias, entry]) => ({
+            alias,
+            enabled: entry.enabled,
+            visibility: entry.visibility,
+            permissions: [...entry.permissions],
+            source_path: entry.source_path,
+            source_repo: entry.source_repo,
+            sources: entry.sources.map((source) => ({
+                label: source.label,
+                path: source.path,
+                enabled: source.enabled,
+                expected_profile: source.expected_profile,
+            })),
+        })),
+    };
+}
+function searchTool(root, args) {
+    const query = requireString(args, "query");
+    const type = optionalString(args, "type")?.toLowerCase();
+    const status = optionalString(args, "status")?.toLowerCase();
+    const limit = clampLimit(optionalInteger(args, "limit"), DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+    const { config, index } = loadReadOnlyIndex(root);
+    const ws = ensureKnownWorkspace(config, normalizeWorkspace(optionalString(args, "ws")));
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const matches = (0, sort_1.sortNodesByQid)((0, filter_1.filterNodes)(Object.values(index.nodes), { ws, type, status }).filter((node) => matchesSearch(node, terms)));
+    return {
+        command: "mcp.search",
+        query,
+        count: matches.length,
+        limit,
+        truncated: matches.length > limit,
+        items: matches.slice(0, limit).map(query_output_1.toNodeSummaryJson),
+    };
+}
+function showTool(root, args) {
+    const id = requireString(args, "id");
+    const metaOnly = optionalBoolean(args, "meta_only") ?? false;
+    const { config, index } = loadReadOnlyIndex(root);
+    const ws = ensureKnownWorkspace(config, normalizeWorkspace(optionalString(args, "ws")));
+    const resolved = (0, qid_1.resolveQid)(index, id, ws);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("id", id, resolved, ws));
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node) {
+        throw new errors_1.NotFoundError(`node not found: ${id}`);
+    }
+    return {
+        command: "mcp.show",
+        item: (0, query_output_1.toNodeDetailJson)(node, metaOnly ? undefined : (0, node_body_1.readNodeBody)(root, node)),
+    };
+}
+function packTool(root, args) {
+    const id = requireString(args, "id");
+    const profile = optionalString(args, "profile") ?? "concise";
+    const maxNodes = clampLimit(optionalInteger(args, "max_nodes"), DEFAULT_PACK_NODES, MAX_PACK_NODES);
+    const maxChars = clampLimit(optionalInteger(args, "max_chars"), DEFAULT_PACK_MAX_CHARS, DEFAULT_PACK_MAX_CHARS);
+    const { config, index } = loadReadOnlyIndex(root);
+    const ws = ensureKnownWorkspace(config, normalizeWorkspace(optionalString(args, "ws")));
+    const resolved = (0, qid_1.resolveQid)(index, id, ws);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("id", id, resolved, ws));
+    }
+    const resolvedProfile = (0, profile_1.resolvePackProfile)({ profile });
+    const built = (0, pack_1.buildPack)({
+        root,
+        index,
+        rootQid: resolved.qid,
+        depth: config.pack.default_depth,
+        edges: [...config.pack.default_edges],
+        verbose: false,
+        maxNodes,
+        verboseCoreListPath: path_1.default.resolve(root, config.pack.verbose_core_list_path),
+        wsHint: ws,
+        includeLatestCheckpoint: true,
+    });
+    const headingMap = resolvedProfile.bodyMode === "summary"
+        ? (0, headings_1.loadTemplateHeadingMap)(root, config, Array.from(node_1.ALLOWED_TYPES))
+        : {};
+    const shaped = (0, profile_1.shapePackBodies)(built.pack, { resolved: resolvedProfile, templateHeadingMap: headingMap });
+    const budgeted = (0, budget_1.applyPackBudgets)(shaped, { maxChars }, resolvedProfile.profile).pack;
+    return {
+        command: "mcp.pack",
+        warnings: built.warnings,
+        pack: budgeted,
+    };
+}
+function goalCurrentTool(root, args) {
+    const { config, index } = loadReadOnlyIndex(root);
+    const ws = ensureKnownWorkspace(config, normalizeWorkspace(optionalString(args, "ws")));
+    const selected = selectedGoalState(root);
+    const selectedNode = selected ? index.nodes[selected.qid] : undefined;
+    if (selectedNode && (!ws || selectedNode.ws === ws)) {
+        return {
+            command: "mcp.goal_current",
+            source: "selected",
+            selected,
+            goal: (0, query_output_1.toNodeSummaryJson)(selectedNode),
+        };
+    }
+    const active = activeGoalCandidates(index, ws);
+    return {
+        command: "mcp.goal_current",
+        source: active.length === 1 ? "unique_active" : "none",
+        selected: selected ?? null,
+        goal: active.length === 1 ? (0, query_output_1.toNodeSummaryJson)(active[0]) : null,
+        active_count: active.length,
+        active_goals: active.map(query_output_1.toNodeSummaryJson),
+    };
+}
+function goalNextTool(root, args) {
+    const { config, index } = loadReadOnlyIndex(root);
+    const ws = ensureKnownWorkspace(config, normalizeWorkspace(optionalString(args, "ws")));
+    const loaded = resolveGoal(root, index, optionalString(args, "id"), ws);
+    const warnings = [...loaded.warnings];
+    if (isArchivedGoal(loaded.node)) {
+        warnings.push(`${loaded.node.qid} is archived and has no actionable next work`);
+        return {
+            command: "mcp.goal_next",
+            goal_source: loaded.source,
+            goal: (0, query_output_1.toNodeSummaryJson)(loaded.node),
+            node: null,
+            warnings,
+        };
+    }
+    const statusPreference = config.work.next.status_preference.map((status) => status.toLowerCase());
+    const statusRanks = new Set(statusPreference);
+    const scope = (0, goal_scope_1.collectGoalScope)(index, loaded.node);
+    for (const missing of scope.missingRefs) {
+        warnings.push(`scope_refs references missing node: ${missing}`);
+    }
+    for (const invalid of scope.invalidRefs) {
+        warnings.push(`scope contains non-actionable or unsupported node: ${invalid}`);
+    }
+    const activeNode = typeof loaded.node.attributes.active_node === "string"
+        ? loaded.node.attributes.active_node
+        : undefined;
+    if (activeNode) {
+        const resolved = (0, qid_1.resolveQid)(index, activeNode, loaded.node.ws);
+        const node = resolved.status === "ok" ? index.nodes[resolved.qid] : undefined;
+        if (node && scope.actionableQids.has(node.qid) && isConcreteGoalCandidate(node, statusRanks)) {
+            return {
+                command: "mcp.goal_next",
+                goal_source: loaded.source,
+                goal: (0, query_output_1.toNodeSummaryJson)(loaded.node),
+                node: (0, query_output_1.toNodeSummaryJson)(node),
+                warnings,
+            };
+        }
+        warnings.push(`active_node is not an actionable local concrete item: ${activeNode}`);
+    }
+    const candidates = Array.from(scope.actionableQids)
+        .map((qid) => index.nodes[qid])
+        .filter((node) => Boolean(node))
+        .filter((node) => isConcreteGoalCandidate(node, statusRanks));
+    const selected = (0, sort_1.sortNodesForNext)(candidates, {
+        statusPreference,
+        priorityMax: config.work.priority_max,
+    })[0];
+    return {
+        command: "mcp.goal_next",
+        goal_source: loaded.source,
+        goal: (0, query_output_1.toNodeSummaryJson)(loaded.node),
+        node: selected ? (0, query_output_1.toNodeSummaryJson)(selected) : null,
+        warnings,
+    };
+}
+function callTool(context, name, args) {
+    switch (name) {
+        case "mdkg_status":
+            return toolResult((0, status_1.collectStatus)(context.root));
+        case "mdkg_workspace_list":
+            return toolResult(listWorkspaces(context.root));
+        case "mdkg_search":
+            return toolResult(searchTool(context.root, args));
+        case "mdkg_show":
+            return toolResult(showTool(context.root, args));
+        case "mdkg_pack":
+            return toolResult(packTool(context.root, args));
+        case "mdkg_goal_current":
+            return toolResult(goalCurrentTool(context.root, args));
+        case "mdkg_goal_next":
+            return toolResult(goalNextTool(context.root, args));
+        case "mdkg_validate":
+            return toolResult((0, validate_1.collectValidateReceipt)({ root: context.root, json: true }));
+        default:
+            throw new errors_1.UsageError(`Unknown tool: ${name}`);
+    }
+}
+function jsonRpcError(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code,
+            message,
+            ...(data === undefined ? {} : { data }),
+        },
+    };
+}
+function jsonRpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function requestId(value) {
+    if (typeof value === "string" || typeof value === "number" || value === null) {
+        return value;
+    }
+    return null;
+}
+function errorCode(err) {
+    if (err instanceof errors_1.UsageError) {
+        return -32602;
+    }
+    if (err instanceof errors_1.NotFoundError) {
+        return -32004;
+    }
+    return -32000;
+}
+function handleMcpRequest(context, raw) {
+    const id = requestId(raw.id);
+    if (raw.jsonrpc !== "2.0" || typeof raw.method !== "string") {
+        return jsonRpcError(id, -32600, "Invalid Request");
+    }
+    if (raw.id === undefined && raw.method !== "notifications/initialized") {
+        return undefined;
+    }
+    try {
+        switch (raw.method) {
+            case "initialize": {
+                const params = asObject(raw.params);
+                const requestedVersion = typeof params.protocolVersion === "string" ? params.protocolVersion : MCP_PROTOCOL_VERSION;
+                return jsonRpcResult(id, {
+                    protocolVersion: requestedVersion === MCP_PROTOCOL_VERSION ? MCP_PROTOCOL_VERSION : MCP_PROTOCOL_VERSION,
+                    capabilities: {
+                        tools: {
+                            listChanged: false,
+                        },
+                    },
+                    serverInfo: {
+                        name: SERVER_NAME,
+                        title: "mdkg local read-only MCP server",
+                        version: (0, version_1.readPackageVersion)(),
+                    },
+                    instructions: "Read-only mdkg graph inspection over stdio. No mutation tools, shell execution, arbitrary file reads, SQL, or environment secret access are exposed.",
+                });
+            }
+            case "notifications/initialized":
+                return undefined;
+            case "ping":
+                return jsonRpcResult(id, {});
+            case "tools/list":
+                return jsonRpcResult(id, { tools: MCP_TOOLS.map(toolDescription) });
+            case "tools/call": {
+                const params = asObject(raw.params);
+                if (typeof params.name !== "string" || params.name.trim().length === 0) {
+                    throw new errors_1.UsageError("tools/call requires params.name");
+                }
+                return jsonRpcResult(id, callTool(context, params.name, asObject(params.arguments)));
+            }
+            default:
+                return jsonRpcError(id, -32601, `Method not found: ${raw.method}`);
+        }
+    }
+    catch (err) {
+        return jsonRpcError(id, errorCode(err), err instanceof Error ? err.message : String(err));
+    }
+}
+function handleMcpMessage(context, message) {
+    if (Array.isArray(message)) {
+        return message
+            .map((item) => handleMcpRequest(context, item))
+            .filter((item) => Boolean(item));
+    }
+    const response = handleMcpRequest(context, message);
+    return response ? [response] : [];
+}
+async function runMcpServeCommand(options) {
+    if (!options.stdio) {
+        throw new errors_1.UsageError("mdkg mcp serve requires --stdio");
+    }
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const lines = readline_1.default.createInterface({
+        input,
+        crlfDelay: Infinity,
+    });
+    const context = { root: options.root };
+    for await (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            output.write(`${JSON.stringify(jsonRpcError(null, -32700, "Parse error"))}\n`);
+            continue;
+        }
+        for (const response of handleMcpMessage(context, parsed)) {
+            output.write(`${JSON.stringify(response)}\n`);
+        }
+    }
+    return 0;
+}