feat(mcp): spar-mcp crate skeleton + read-only tools (Track E commit 8 / v0.9.0) (#179)

New `spar-mcp` crate exposing spar's hypothetical-rebinding oracle as
MCP (Model Context Protocol) tools so LLM agents can drive design-space
exploration with spar as the deterministic correctness oracle.

Three read-only / idempotent tools:
- `spar.verify_move` — single hypothetical-rebinding check
- `spar.enumerate_moves` — design-space exploration with multi-objective ranking
- `spar.check_chain` — end-to-end latency breakdown for a chain

Architecture:
- `spar-cli` promoted to lib + bin so verify/enumerate logic is shareable
- `spar-mcp` consumes the lib API in-process; no shell-out / re-parsing
- stdio JSON-RPC transport (Initialize, tools/list, tools/call)
- All tools `readOnlyHint: true` and `idempotentHint: true` per spec
- Deterministic apply path stays CLI-exclusive (no `spar.apply_move` over MCP)

Tests: 11 (5 in-process + 6 stdio).

REQ-MCP-001 + TEST-MCP-* in artifacts/.

Closes Track E commit 8/8 of the v0.8.0 migration design carved out as
v0.9.0 scope per docs/designs/track-e-migration-research.md §6.5.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: avrabe

Cargo.lock

@@ -12,6 +12,7 @@ members = [
     "crates/spar-transform",
     "crates/spar-variants",
     "crates/spar-cli",
+    "crates/spar-mcp",
     "crates/spar-codegen",
     "crates/spar-render",
     "crates/spar-solver",

Cargo.toml

@@ -1495,4 +1495,30 @@ artifacts:
     status: implemented
     tags: [insight, trace, cli, v090]
 
+  # ── Track E commit 8/8 — MCP oracle surface (v0.9.0) ──────────────────
+
+  - id: REQ-MCP-002
+    type: requirement
+    title: spar-mcp read-only verification-oracle tool surface
+    description: >
+      System exposes read-only / idempotent MCP (Model Context Protocol)
+      tools `spar.verify_move`, `spar.enumerate_moves`, and
+      `spar.check_chain` for AI agent integration. The three tools wrap
+      the existing `spar moves verify`, `spar moves enumerate`, and
+      end-to-end latency-analysis pipelines without printing — each tool
+      returns the same structured JSON shape the equivalent CLI
+      subcommand emits with `--format json`. The deterministic apply
+      path stays CLI-exclusive: there is no `spar.apply_move` tool over
+      MCP, ever, by certification design (per Track E migration research
+      §6.5). LLM agents propose moves; spar deterministically verifies;
+      certification chain stays in spar. The transport is JSON-RPC 2.0
+      over stdio per MCP 2025-11-25; the server is reachable as either a
+      standalone `spar-mcp` binary or via the `spar mcp serve`
+      subcommand. All three tools declare `readOnlyHint: true` and
+      `idempotentHint: true` in their MCP annotations and refuse to
+      mutate the model file on disk. Track E commit 8/8 of the v0.9.0
+      design.
+    status: implemented
+    tags: [mcp, migration, track-e, v090, integration]
+
   # Research findings tracked separately in research/findings.yaml

artifacts/requirements.yaml

@@ -1952,3 +1952,50 @@ artifacts:
         target: REQ-INSIGHT-001
       - type: satisfies
         target: REQ-INSIGHT-002
+
+  # ── Track E commit 8/8 — MCP oracle tool surface (v0.9.0) ────────────
+
+  - id: TEST-MCP-TOOLS
+    type: feature
+    title: spar-mcp read-only verification-oracle tool surface tests
+    description: >
+      Integration tests in crates/spar-mcp/tests covering the v0.9.0
+      MCP tool surface (Track E commit 8/8). Eleven tests split between
+      an in-process Rust API path (5) and a stdio JSON-RPC envelope path
+      (6). Coverage:
+      (1) `spar.verify_move` returns ok=true and exit_code=0 on an
+          admissible mobile-component move;
+      (2) `spar.enumerate_moves` enumerates every Processor /
+          VirtualProcessor in the instance when no Allowed_Targets is
+          set;
+      (3) `spar.check_chain` returns the latency-pass diagnostic stream
+          (best/worst-case bounds plus per-hop annotations) for a chain
+          spanning one compute hop and one connection hop;
+      (4) variant scoping (`--variant NAME` over the
+          SPAR_VARIANT_TEST_RIVET_OUTPUT seam) populates the report's
+          `variant` and `feature_model_hash` audit fields;
+      (5) the `--objective` selector accepts the five recognised modes
+          and rejects unknown values with a BAD_INPUT error;
+      (6) `tools/list` returns exactly three tools with
+          `readOnlyHint: true` / `idempotentHint: true`;
+      (7-9) `tools/call` for each tool returns valid JSON with the
+          documented `structuredContent` shape and `isError: false`;
+      (10) an unknown tool name returns the JSON-RPC MethodNotFound
+          error code (-32601);
+      plus one bonus test confirming unknown JSON-RPC methods (e.g.
+      `sampling/createMessage`) also return -32601.
+    fields:
+      method: automated-test
+      steps:
+        - run: cargo test -p spar-mcp
+    status: passing
+    tags: [mcp, migration, track-e, v090, integration]
+    links:
+      - type: satisfies
+        target: REQ-MCP-002
+      - type: satisfies
+        target: REQ-MIGRATION-005
+      - type: satisfies
+        target: REQ-MIGRATION-006
+      - type: satisfies
+        target: REQ-MIGRATION-008

artifacts/verification.yaml

@@ -6,6 +6,10 @@ license.workspace = true
 repository.workspace = true
 description = "AADL toolchain CLI"
 
+[lib]
+name = "spar_cli"
+path = "src/lib.rs"
+
 [[bin]]
 name = "spar"
 path = "src/main.rs"

crates/spar-cli/Cargo.toml

@@ -0,0 +1,23 @@
+//! Public library surface for `spar-cli`.
+//!
+//! `spar-cli` is primarily a binary crate (`spar`); the library exposes
+//! the *internals* needed by sibling crates — currently:
+//!
+//! - [`moves`] — the verify / enumerate pipelines used by the v0.9.0
+//!   MCP tool surface ([`spar-mcp`](../spar_mcp/index.html)). The MCP
+//!   tools call [`moves::verify_pipeline`] and
+//!   [`moves::enumerate_pipeline`] directly so the wire-format report
+//!   shape stays a single source of truth across CLI and MCP transport.
+//!
+//! Everything else (LSP, codegen dispatch, refactor, diff, sarif) is
+//! still private to the binary and exposed only via `spar <command>`.
+//!
+//! # Stability
+//!
+//! This is an internal-use-only library; the public surface only
+//! supports the in-tree `spar-mcp` consumer. External users should
+//! shell out to `spar` (or, for v0.9.0+, drive the MCP server) rather
+//! than depend on this crate as a Rust library.
+
+pub mod moves;
+pub mod variants_bridge;

crates/spar-cli/src/lib.rs

@@ -2,12 +2,18 @@ mod assertion;
 mod diff;
 mod insight;
 mod lsp;
-mod moves;
 mod refactor;
 mod sarif;
-mod variants_bridge;
 mod verify;
 
+// Re-export shared modules from the library so the binary keeps using
+// the `crate::moves::…` / `crate::variants_bridge::…` paths in its
+// existing call sites without duplicating module bodies. The lib
+// (spar_cli) is the canonical home; spar-mcp consumes the same surface.
+use spar_cli::moves;
+#[allow(unused_imports)]
+use spar_cli::variants_bridge;
+
 use std::{env, fs, process};
 
 use serde::Serialize;
@@ -44,6 +50,7 @@ fn main() {
         "extract" => cmd_sysml2_extract(&args[2..]),
         "generate" => cmd_sysml2_generate(&args[2..]),
         "lsp" => cmd_lsp(),
+        "mcp" => cmd_mcp(&args[2..]),
         "moves" => moves::cmd_moves_dispatch(&args[2..]),
         "insight" => insight::cmd_insight(&args[2..]),
         other => {
@@ -72,6 +79,9 @@ fn print_usage() {
     );
     eprintln!("  insight    Discrepancy assistant: compare CTF traces to Expected_BCET/WCET/Mean");
     eprintln!("  lsp        Start Language Server Protocol server (stdin/stdout)");
+    eprintln!(
+        "  mcp        Start MCP server (read-only verification oracles for AI agent integration)"
+    );
     eprintln!();
     eprintln!("Options:");
     eprintln!("  parse    [--tree] <file...>");
@@ -107,6 +117,102 @@ fn cmd_lsp() {
     lsp::run_lsp_server();
 }
 
+/// `spar mcp serve` — start the spar-mcp stdio JSON-RPC server.
+///
+/// The actual server lives in the sibling `spar-mcp` crate. To avoid a
+/// Cargo cycle (spar -> spar-mcp -> spar-cli (lib) -> spar binary), we
+/// exec the standalone `spar-mcp` binary that ships alongside `spar`.
+/// We resolve it via:
+///
+/// 1. `$SPAR_MCP_BIN` if set;
+/// 2. a sibling of the current executable (`<dir>/spar-mcp[.exe]`);
+/// 3. the host `$PATH`.
+fn cmd_mcp(args: &[String]) {
+    let usage = || {
+        eprintln!("Usage: spar mcp serve");
+        eprintln!();
+        eprintln!("Subcommands:");
+        eprintln!(
+            "  serve   Start the MCP stdio JSON-RPC server (read-only / idempotent oracle tools)"
+        );
+    };
+
+    let sub = match args.first().map(String::as_str) {
+        None | Some("--help") | Some("-h") => {
+            usage();
+            process::exit(if args.is_empty() { 1 } else { 0 });
+        }
+        Some("serve") => "serve",
+        Some(other) => {
+            eprintln!("Unknown mcp subcommand: {other}");
+            usage();
+            process::exit(1);
+        }
+    };
+
+    if sub != "serve" {
+        // Defensive: should be unreachable given the match above.
+        usage();
+        process::exit(1);
+    }
+
+    let bin = match locate_spar_mcp_binary() {
+        Some(p) => p,
+        None => {
+            eprintln!(
+                "spar-mcp binary not found (searched $SPAR_MCP_BIN, the directory of the \
+                 current spar binary, and $PATH). Build the workspace with `cargo build -p \
+                 spar-mcp` and re-run."
+            );
+            process::exit(1);
+        }
+    };
+
+    // Replace the current process so stdio is shared 1:1 with the
+    // child — no buffering layer between the JSON-RPC client and the
+    // server loop.
+    let err = std::process::Command::new(&bin).args(&args[1..]).status();
+    match err {
+        Ok(status) => process::exit(status.code().unwrap_or(1)),
+        Err(e) => {
+            eprintln!("failed to execute {}: {e}", bin.display());
+            process::exit(1);
+        }
+    }
+}
+
+/// Locate the `spar-mcp` binary on disk. See [`cmd_mcp`] for the
+/// resolution order.
+fn locate_spar_mcp_binary() -> Option<std::path::PathBuf> {
+    if let Some(v) = std::env::var_os("SPAR_MCP_BIN") {
+        let p = std::path::PathBuf::from(v);
+        if p.is_file() {
+            return Some(p);
+        }
+    }
+    if let Ok(self_exe) = std::env::current_exe()
+        && let Some(dir) = self_exe.parent()
+    {
+        for name in ["spar-mcp", "spar-mcp.exe"] {
+            let candidate = dir.join(name);
+            if candidate.is_file() {
+                return Some(candidate);
+            }
+        }
+    }
+    if let Some(path) = std::env::var_os("PATH") {
+        for dir in std::env::split_paths(&path) {
+            for name in ["spar-mcp", "spar-mcp.exe"] {
+                let candidate = dir.join(name);
+                if candidate.is_file() {
+                    return Some(candidate);
+                }
+            }
+        }
+    }
+    None
+}
+
 fn cmd_parse(args: &[String]) {
     let mut show_tree = false;
     let mut files = Vec::new();