MCP server: reload and staleness detection for the spawn-time snapshot

[jimisola]

Problem

reqstool mcp local -p <path> loads everything — the requirements/SVC YAML model and the generated annotation/test-result artifacts — once at spawn, then serves that snapshot indefinitely with no reload and no staleness signal.

Observed in a real project (skills-gateway), where the MCP server is spawned by an AI coding harness and stays alive for days:

• Long-lived server (spawned days earlier): get_status returned 14 requirements, 0 implementations, 0 tests.
• Reality at query time (CLI reqstool status local after mvn clean verify): 55/55 complete, PASS.
• Freshly spawned server against the same tree + fresh build: 55 requirements, 55 completed, 54 with implementation, 59 tests — matching the CLI exactly.

So the join logic is fine; the failure mode is silent staleness. Dangerous because the stale answer is well-formed — an agent (or human) has no way to distinguish "0 implementations" from "snapshot predates the build".

Proposal

1. Reload: re-read sources + artifacts per request, or watch files, or expose an explicit refresh tool. Per-request re-read is likely fine at these scales.
2. Staleness detection: status-type responses should compare artifact/source mtimes against the loaded snapshot (and against each other) and either transparently reload or answer STALE — rebuild/reload required instead of confident numbers. Truncated/absent artifacts (the incremental-compilation trap) should be reported as such, never as zeros.
3. (Optional) a verify tool with CLI-gate semantics: {complete, incomplete, failing: [ids+reasons], pass: bool} — the machine-readable equivalent of "N/N complete · PASS", usable by agents mid-loop once 1+2 make it trustworthy.

Interim guidance for consumers is in reqstool/reqstool-ai#36 (MCP to read, YAML to edit, CLI to verify).

🤖 Generated with Claude Code

[jimisola]

Proposed solution (implementation plan for follow-up)

Analysis of current main (0a685af) confirms the failure mode and points to a two-part fix: a concrete closure bug in the MCP server, plus missing input-file fingerprinting. Plan below is self-contained with file/line pointers so another agent can pick it up.

Root causes (two, not one)

1. Stale closure capture — src/reqstool/mcp/server.py:44-45 copies session.repo and session.urn_source_paths into locals at spawn; every @mcp.tool() closure binds those locals. ProjectSession.rebuild() already exists (src/reqstool/common/project_session.py:85, used by the LSP on file save/watch), but calling it would be invisible to the MCP tools — they'd keep querying the old, closed repo. Any reload mechanism must first fix this: tools must resolve session.repo per call, never at spawn.
2. No input fingerprint — source_paths records only the 4 YAMLs (requirements/svcs/mvrs/annotations) and only for LocalLocation (combined_raw_datasets_generator.py:332-348). JUnit XML files are resolved from glob patterns at parse time (__parse_source_other, combined_raw_datasets_generator.py:372-380) and the matched file list is discarded. So there is nothing to compare mtimes against, and "pattern matched 0 files" is indistinguishable from "no tests" — the incremental-compilation trap from the issue.

Note: unlike LSP, MCP has no client file-watch channel (didChangeWatchedFiles doesn't exist in MCP), so server-side stat-based staleness checks are the right mechanism, not watching.

Design

1. SnapshotFingerprint (new: src/reqstool/common/snapshot_fingerprint.py)

Captured during build, cheap to re-check (a few dozen stat()s + re-globs per request):

@dataclass(frozen=True)
class FileStamp:      # one per parsed local input file
    path: str
    mtime_ns: int
    size: int

@dataclass(frozen=True)
class GlobSpec:       # one per test_results pattern, per local URN node
    root: str         # resolved actual_tmp_path / local dir
    pattern: str
    matched: tuple[str, ...]   # concrete files matched at build time

@dataclass(frozen=True)
class SnapshotFingerprint:
    built_at: str               # ISO timestamp
    stamps: tuple[FileStamp, ...]
    globs: tuple[GlobSpec, ...]

    def is_stale(self) -> bool:
        # any stamped file missing, or mtime_ns/size changed -> True
        # any glob re-evaluated to a different file set -> True (catches NEW junit xml)

Data collection points:

• __parse_source_other (combined_raw_datasets_generator.py:372-380): test_result_files is already in hand — record it together with (actual_tmp_path, pattern) instead of discarding.
• __extract_source_paths already yields the YAML paths; also stamp reqstool_config.yml when present (requirements_indata.py:45-46) — a config edit changes which files are parsed.
• LocalLocation uses a symlink into tmp (requirements_indata.py:82 resolves via os.readlink) — stamp the resolved paths.
• Remote locations (git/maven/pypi/npm) are downloaded snapshots pinned to a version: treat as immutable, skip. (A GitLocation on a moving branch ref is technically mutable — out of scope, document it.)

Plumbing: add input_file_stamps / test_result_globs fields to RawDataset and aggregate onto CombinedRawDataset (src/reqstool/models/raw_datasets.py), mirroring how urn_source_paths flows today (combined_raw_datasets_generator.py:73-83 → project_session.py:73).

2. Auto-reload in ProjectSession

def ensure_fresh(self) -> None:
    """Rebuild iff the captured fingerprint no longer matches disk."""
    with self._lock:
        if self._fingerprint is not None and self._fingerprint.is_stale():
            self.build()   # build() re-captures the fingerprint

• build() captures self._fingerprint from the CombinedRawDataset.
• Reload failure (e.g. mid-edit broken YAML, common in an AI-harness loop): do not silently keep serving the old snapshot. ensure_fresh() raises with the parse error; the MCP tool surfaces it as a tool error ("project sources changed but reload failed: <error>"). That honors the issue's core requirement — never confident numbers from a snapshot known to be stale. Keep old DB state around so a subsequent successful reload recovers.
• Concurrency: MCP tools are async, build() is sync. Serialize tool bodies through self._lock (traffic is per-agent, low; simplest correct option). Optional: min-interval (~1s) between stat sweeps to debounce bursts.

3. MCP server changes (src/reqstool/mcp/server.py)

• Remove the spawn-time repo / urn_source_paths locals (lines 44-45). Add a helper each tool calls first:

  def _repo() -> RequirementsRepository:
      session.ensure_fresh()          # raises on failed reload
      return session.repo

• refresh tool (explicit, per proposal pt. 1): forces session.build(), returns {reloaded: true, built_at, requirements: N, annotations: N, tests: N}. Useful even with auto-reload — a harness can force + confirm right after mvn verify.

• Snapshot metadata (proposal pt. 2): extend get_status (and/or add get_snapshot_info) with:

  "snapshot": {
    "built_at": "...",
    "reload": "auto",
    "warnings": ["test_results pattern 'target/failsafe-reports/*.xml' matched 0 files"]
  }

  The zero-match warning comes straight from the recorded GlobSpecs — this turns "absent artifacts reported as zeros" into an explicit signal.

4. Optional verify tool (proposal pt. 3)

{complete, incomplete, failing: [{id, reasons}], pass} — must derive from StatisticsService's per-requirement computation (to_status_dict() is already 90% of it). Per the single-source-of-truth rule from #412/#411: no parallel verdict path. Worth checking against the #311 status/export redesign before finalizing the shape.

Why not per-request full re-read?

Per-request rebuild (proposal option "re-read per request") is simpler but re-parses the whole import chain — including remote locations (network fetches for git/maven/pypi imports) — on every tool call. Fingerprint-check-then-rebuild gives the same freshness for local sources at ~stat cost, and remote imports are version-pinned anyway. If implementation effort must be minimized, per-request ensure_fresh() with rebuild-on-any-change is still strictly better than per-request unconditional rebuild.

Tests

• Unit (tests/unit/reqstool/common/): fingerprint — touch/rewrite annotations.yml → stale; drop a new JUnit XML matching a recorded pattern → stale (the skills-gateway scenario); unchanged tree → fresh; deleted file → stale.
• Integration (tests/integration/reqstool/mcp/test_mcp_integration.py): spawn server against a temp copy of a fixture → get_status → append an annotation impl + a passing JUnit XML → get_status again returns updated numbers without respawn; corrupt requirements.yml → tool call errors with reload failure (not stale numbers); refresh tool round-trip.
• Zero-match warning: fixture with a test_results pattern matching nothing → get_status.snapshot.warnings non-empty.

Suggested split

1. PR 1 — fingerprint capture + ProjectSession.ensure_fresh() + MCP closure fix + auto-reload (fixes the reported staleness end-to-end).
2. PR 2 — refresh tool + snapshot metadata/warnings in get_status.
3. PR 3 (optional, after feat: add --verbosity levels (compact, normal, verbose) to status command (console only) #311 alignment) — verify tool.

🤖 Generated with Claude Code