mdkg 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -8,9 +8,35 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
-### Planned
+## 0.3.6 - 2026-06-17
 
-- No changes yet.
+### Added
+
+- Added `mdkg mcp serve --stdio` as a local read-only MCP server for status,
+  workspace/subgraph discovery, search, show, bounded in-memory packs, goal
+  current/next, and validation.
+- Added packed `smoke:mcp` coverage that installs mdkg from a tarball in a
+  temp prefix, launches the stdio server, exercises root and subgraph reads,
+  and proves mutation-shaped tool calls fail closed.
+
+### Fixed
+
+- Prepared `0.3.6` graph import hardening after the `0.3.5` publish:
+  `mdkg graph import-template --select-goal --apply` now activates the
+  rewritten imported start goal, pauses competing active root goals, validates,
+  and only then writes selected-goal state.
+
+### Changed
+
+- Extended graph import dry-run/apply receipts with activation and paused-goal
+  details, and made active template imports fail before writing when
+  `--select-goal` is omitted and multiple active root goals would result.
+
+### Security
+
+- The MCP server is stdio-only and exposes no task, goal activation, graph
+  import, queue, event, archive, format, SQL, shell, arbitrary file-read,
+  filesystem mutation, environment, or secret-access tools.
 
 ## 0.3.5 - 2026-06-17
 

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
 as_of: 2026-06-17
-package_version_in_source: 0.3.5
+package_version_in_source: 0.3.6
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -36,6 +36,7 @@ Primary commands:
 - `next`
 - `validate`
 - `status`
+- `mcp`
 - `fix`
 
 Advanced / maintenance commands:
@@ -64,6 +65,7 @@ Fresh init workspaces default to the SQLite access cache backend; existing migra
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
 Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
+Local MCP integration is accessed through `mdkg mcp serve --stdio`; it exposes read-only graph/status/workspace/search/show/pack/goal/validate tools only.
 
 ## Global usage
 
@@ -647,13 +649,14 @@ Notes:
 - `graph import-template` defaults to dry-run unless `--apply` is supplied
 - same-repo template import rewrites canonical numeric IDs to the next unused ID by type prefix and rewrites structured refs plus safe body-local id/qid mentions
 - colliding semantic template IDs require `--id-prefix`
-- `--select-goal` requires `--start-goal` and writes selected-goal state only after apply validation
+- `--select-goal` requires `--start-goal`; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state
+- importing active template goals without `--select-goal` fails before writing when it would create multiple active root goals
 - subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
 
 JSON receipts:
 - `clone`: `{ action: "graph.clone", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, index, validation, warnings }`
 - `fork`: `{ action: "graph.fork", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, start_goal?, selected_goal?, index, validation, warnings }`
-- `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, index?, validation?, warnings }`
+- `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, activated_goal?, paused_goals, index?, validation?, warnings }`
 
 ### `mdkg subgraph`
 
@@ -1086,6 +1089,34 @@ JSON receipt shape:
 - `generated` reports index, skills, capabilities, and subgraph cache existence/staleness
 - `summary` includes machine-readable warning and error counts plus messages
 
+### `mdkg mcp`
+
+Usage:
+- `mdkg mcp serve --stdio`
+
+When to use:
+- expose one local mdkg root to an MCP-capable agent or orchestrator
+- let an external agent inspect mdkg status, workspace/subgraph aliases, search/show results, in-memory packs, goal current/next, and validation without shelling out to individual CLI commands
+
+Flags:
+- `--stdio`
+- `--root`, `-r <path>`
+
+Boundaries:
+- stdio is the only transport in this release; mdkg opens no HTTP listener
+- bind the server to one graph root with `--root <path>` when launching from outside the repo
+- tool calls are read-only and return MCP `structuredContent` plus text content
+- exposed tools: `mdkg_status`, `mdkg_workspace_list`, `mdkg_search`, `mdkg_show`, `mdkg_pack`, `mdkg_goal_current`, `mdkg_goal_next`, and `mdkg_validate`
+- `mdkg_pack` builds an in-memory bounded pack and does not write `.mdkg/pack`
+- no task, goal activation, graph import, queue, event, archive, format, SQL, shell, arbitrary file-read, filesystem mutation, environment, or secret-access tool is exposed
+- mutation allowlists and broader CLI parity are future design work, not part of this command surface
+- stdout is reserved for newline-delimited JSON-RPC MCP messages; diagnostics must stay off stdout
+
+JSON-RPC receipt shapes:
+- initialize: `{ protocolVersion, capabilities: { tools }, serverInfo, instructions }`
+- `tools/list`: `{ tools: [{ name, title, description, inputSchema, annotations }] }`
+- `tools/call`: MCP tool result with `{ content, structuredContent, isError }`
+
 ### `mdkg fix`
 
 When to use:

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.3.5`
+Current package version in source: `0.3.6`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -167,9 +167,11 @@ mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 -
 ```
 
 `graph clone` and `graph fork` preserve IDs; `graph import-template` rewrites
-canonical numeric IDs and internal links to avoid same-repo collisions. Subgraphs
-remain read-only planning views; use `mdkg graph ...` when authored graph state
-should be created.
+canonical numeric IDs and internal links to avoid same-repo collisions. With
+`--select-goal --apply`, import-template activates the rewritten imported start
+goal, pauses competing active root goals, validates the graph, and then writes
+selected-goal state. Subgraphs remain read-only planning views; use
+`mdkg graph ...` when authored graph state should be created.
 
 Register a child repo bundle as a read-only subgraph planning view:
 
@@ -206,6 +208,20 @@ Materialized trees are generated local state, ignored by graph indexing/search/v
 
 Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
+Launch a local read-only MCP server when an MCP-capable agent should inspect a
+specific mdkg graph without receiving mutation tools:
+
+```bash
+mdkg mcp serve --stdio --root /path/to/repo
+```
+
+The MCP surface is stdio-only in this release. It exposes read-only tools for
+status, workspace/subgraph listing, search, show, in-memory pack generation,
+goal current/next, and validation. It does not expose task updates, goal
+activation, graph import, queue, event, archive, format, SQL, shell, arbitrary
+file reads, filesystem mutation, environment variables, or secret access.
+Future mutation allowlists remain design work.
+
 Validate before handoff or commit:
 
 ```bash
@@ -330,6 +346,7 @@ These are the commands new users and agents should learn first:
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status`
+- `mdkg mcp`
 - `mdkg fix`
 
 Advanced / maintenance commands still exist, but they are not the first-run story:

package/dist/cli.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
+exports.runCliAsync = runCliAsync;
 exports.main = main;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -19,6 +20,7 @@ const validate_1 = require("./commands/validate");
 const format_1 = require("./commands/format");
 const doctor_1 = require("./commands/doctor");
 const status_1 = require("./commands/status");
+const mcp_1 = require("./commands/mcp");
 const fix_1 = require("./commands/fix");
 const db_1 = require("./commands/db");
 const capability_1 = require("./commands/capability");
@@ -78,6 +80,7 @@ function printUsage(log) {
     log("  next        Suggest the next work item");
     log("  validate    Validate frontmatter + graph");
     log("  status      Show read-only operator health summary");
+    log("  mcp         Serve local read-only MCP tools over stdio");
     log("  fix         Plan read-only repairs with receipt-shaped JSON");
     log("\nAdvanced / maintenance commands:");
     log("  db          Project database and index-cache commands");
@@ -581,7 +584,7 @@ function printGraphHelp(log, subcommand) {
             log("  - imports authored .mdkg/work template nodes into the current graph");
             log("  - defaults to dry-run unless --apply is supplied");
             log("  - rewrites canonical numeric IDs and structured graph links deterministically");
-            log("  - --select-goal requires --start-goal and writes selected-goal state only after apply validation");
+            log("  - --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state");
             break;
         default:
             log("Usage:");
@@ -923,6 +926,29 @@ function printStatusHelp(log) {
     log("  --json                Emit machine-readable JSON output");
     printGlobalOptions(log);
 }
+function printMcpHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "serve":
+            log("Usage:");
+            log("  mdkg mcp serve --stdio");
+            log("\nBoundary:");
+            log("  - starts one local Model Context Protocol server bound to the selected --root");
+            log("  - stdio is the only transport in this release; no HTTP listener is opened");
+            log("  - exposes read-only tools for status, workspace list, search, show, pack, goal current/next, and validate");
+            log("  - exposes no task, goal, graph, queue, event, archive, format, SQL, shell, filesystem, or environment mutation tools");
+            log("  - stdout is reserved for newline-delimited JSON-RPC MCP messages");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg mcp serve --stdio");
+            log("\nBoundary:");
+            log("  - local read-only MCP server for mdkg graph inspection");
+            log("  - use --root <path> to select the mdkg graph explicitly");
+            log("  - phase one is stdio-only and does not expose mutation tools");
+            printGlobalOptions(log);
+    }
+}
 function printFixHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "plan":
@@ -1091,6 +1117,9 @@ function printCommandHelp(log, command, subcommand) {
         case "status":
             printStatusHelp(log);
             return;
+        case "mcp":
+            printMcpHelp(log, subcommand);
+            return;
         case "fix":
             printFixHelp(log, subcommand);
             return;
@@ -2788,6 +2817,8 @@ function runCommand(parsed, root, runtime) {
             (0, status_1.runStatusCommand)({ root, json });
             return 0;
         }
+        case "mcp":
+            throw new errors_1.UsageError("mcp serve requires the async CLI entrypoint");
         case "fix": {
             const sub = (parsed.positionals[1] ?? "").toLowerCase();
             if (!sub) {
@@ -2838,6 +2869,18 @@ function runCommand(parsed, root, runtime) {
             return 1;
     }
 }
+async function runMcpSubcommand(parsed, root) {
+    const sub = (parsed.positionals[1] ?? "").toLowerCase();
+    if (sub !== "serve") {
+        throw new errors_1.UsageError("mcp requires serve --stdio");
+    }
+    if (parsed.positionals.length > 2) {
+        throw new errors_1.UsageError("mcp serve does not accept positional arguments");
+    }
+    const stdio = parseBooleanFlag("--stdio", parsed.flags["--stdio"]);
+    await (0, mcp_1.runMcpServeCommand)({ root, stdio });
+    return 0;
+}
 function runCli(argv, runtime = {}) {
     const io = resolveRuntime(runtime);
     const parsed = (0, argparse_1.parseArgs)(argv);
@@ -2875,8 +2918,53 @@ function runCli(argv, runtime = {}) {
         return handleCommandError(err, command, io);
     }
 }
+async function runCliAsync(argv, runtime = {}) {
+    const io = resolveRuntime(runtime);
+    const parsed = (0, argparse_1.parseArgs)(argv);
+    if (parsed.error) {
+        io.error(parsed.error);
+        printUsage(io.log);
+        return 1;
+    }
+    if (parsed.help) {
+        printCommandHelp(io.log, parsed.positionals[0], parsed.positionals[1]);
+        return 0;
+    }
+    if (parsed.version) {
+        io.log(readPackageVersion());
+        return 0;
+    }
+    const command = (parsed.positionals[0] ?? "").toLowerCase();
+    if (!command) {
+        printUsage(io.log);
+        return 0;
+    }
+    if (command === "help") {
+        printCommandHelp(io.log, parsed.positionals[1], parsed.positionals[2]);
+        return 0;
+    }
+    const root = parsed.root ? path_1.default.resolve(parsed.root) : io.cwd();
+    if (shouldRequireConfig(command, parsed.flags) && !hasConfig(root)) {
+        printRootError(io.error, root);
+        return 1;
+    }
+    try {
+        if (command === "mcp") {
+            return await runMcpSubcommand(parsed, root);
+        }
+        return runCommand(parsed, root, io);
+    }
+    catch (err) {
+        return handleCommandError(err, command, io);
+    }
+}
 function main(argv = process.argv.slice(2)) {
-    process.exit(runCli(argv, { cwd: () => process.cwd() }));
+    runCliAsync(argv, { cwd: () => process.cwd() })
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(4);
+    });
 }
 if (require.main === module) {
     main();

package/dist/command-contract.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "package_version": "0.3.5",
+  "package_version": "0.3.6",
   "source": {
     "help_targets": "scripts/cli_help_targets.js",
     "command_matrix": "CLI_COMMAND_MATRIX.md"
@@ -4012,13 +4012,13 @@
           "name": "--select-goal",
           "value": "requires",
           "required": false,
-          "description": "- --select-goal requires --start-goal and writes selected-goal state only after apply validation"
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
         },
         {
           "name": "--start-goal",
-          "value": "and",
+          "value": null,
           "required": false,
-          "description": "- --select-goal requires --start-goal and writes selected-goal state only after apply validation"
+          "description": "- --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state"
         },
         {
           "name": "--version",
@@ -4404,6 +4404,159 @@
         "command_matrix": "CLI_COMMAND_MATRIX.md"
       }
     },
+    {
+      "key": "mcp",
+      "path": [
+        "mcp"
+      ],
+      "category": "mcp",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg mcp command",
+      "usage": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": "<path>",
+          "required": false,
+          "description": "- use --root <path> to select the mdkg graph explicitly"
+        },
+        {
+          "name": "--stdio",
+          "value": null,
+          "required": false,
+          "description": "mdkg mcp serve --stdio"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "docs": {
+        "help_target": "mdkg help mcp",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
+    {
+      "key": "mcp serve",
+      "path": [
+        "mcp",
+        "serve"
+      ],
+      "category": "mcp",
+      "status": "stable",
+      "visibility": "public",
+      "summary": "mdkg mcp serve command",
+      "usage": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "args": [],
+      "flags": [
+        {
+          "name": "--help",
+          "value": null,
+          "required": false,
+          "description": "--help, -h          Show help"
+        },
+        {
+          "name": "--root",
+          "value": null,
+          "required": false,
+          "description": "- starts one local Model Context Protocol server bound to the selected --root"
+        },
+        {
+          "name": "--stdio",
+          "value": null,
+          "required": false,
+          "description": "mdkg mcp serve --stdio"
+        },
+        {
+          "name": "--version",
+          "value": null,
+          "required": false,
+          "description": "--version, -V       Show version"
+        }
+      ],
+      "output_formats": [
+        "text"
+      ],
+      "json_schema_ref": null,
+      "side_effects": [
+        "none"
+      ],
+      "read_paths": [
+        ".mdkg/**"
+      ],
+      "write_paths": [],
+      "dry_run": {
+        "supported": false
+      },
+      "lock_policy": "none-read-only",
+      "atomic_write_policy": "none-read-only",
+      "receipts": [],
+      "danger_level": "read-only",
+      "aliases": [],
+      "exit_codes": [
+        {
+          "code": 0,
+          "meaning": "success"
+        },
+        {
+          "code": 1,
+          "meaning": "validation-or-runtime-error"
+        }
+      ],
+      "examples": [
+        "  mdkg mcp serve --stdio"
+      ],
+      "docs": {
+        "help_target": "mdkg help mcp serve",
+        "command_matrix": "CLI_COMMAND_MATRIX.md"
+      }
+    },
     {
       "key": "new",
       "path": [
@@ -8215,5 +8368,5 @@
       }
     }
   ],
-  "contract_hash": "2fd862666a24adc363a0912822b639f7e437bf5fd31dea13e6f4d87bf0a57d60"
+  "contract_hash": "130236f8a2c5c757528f82acf95f43fb67809a0ddb333ebffa5d69b452a20146"
 }