fix(mcp): ${CLAUDE_PLUGIN_ROOT} substitution + cortex-doctor mcp diagnostic (#22)

* fix(mcp): robust .mcp.json + cortex-doctor mcp diagnostic (v3.15.2)

Discord user reported MCP server "✘ failed" with no actionable error.
Root cause: .mcp.json used a fragile Python -c one-liner that swallowed
launcher startup errors and depended on installed_plugins.json having a
specific key shape that breaks across plugin upgrades, custom marketplace
names, and missing python3 symlinks.

Fixes:
- .mcp.json now uses ${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py — Anthropic's
  documented plugin substitution variable, already used by every hook in
  this repo (.claude/hooks/hooks.json). The launcher self-orients via
  __file__ so manual installs continue to work (backward compatible).
- New `cortex-doctor mcp` subcommand: end-to-end MCP startup diagnostics.
  Tells the user exactly which check failed, what command/path was tried,
  and the actual error string — no more silent failures. Use --json for
  Discord-paste-friendly output.
- 36 new tests (test_doctor_mcp.py + scripts/test_launcher_resolution.py)
  cover happy path + every named failure mode (missing plugins.json,
  missing key, stale installPath, missing launcher, broken launcher,
  unset DATABASE_URL). Plus 6 contract tests guarding .mcp.json shape
  against regression to the inline `-c` wrapper.

Backward compatible:
- `cortex-doctor` (no args) preserves legacy full-setup verification.
- launcher.py still self-orients via __file__ for manual installs.

Platform-agnostic: no Windows/Mac-specific code paths.

Bumps: pyproject.toml + .claude-plugin/marketplace.json → 3.15.2;
CHANGELOG entry added.

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

* fix(mcp): add cortex-doctor mcp + launcher tests + v3.15.2 bump

Completes the v3.15.2 release started in fbf9354 (which only captured
.mcp.json + the contract test due to a staging hiccup):

- mcp_server/doctor_mcp.py — new module implementing `cortex-doctor mcp`
  end-to-end MCP startup diagnostics. Each check reports the exact
  command/path attempted and the actual error string; supports --json
  for Discord-paste-friendly output. Covers: python interpreter on PATH,
  installed_plugins.json shape, CLAUDE_PLUGIN_ROOT env, launcher smoke
  probe (catches errors the old `-c` wrapper hid), DATABASE_URL, PG
  reachability, pgvector/pg_trgm extensions, critical Python deps, and
  optional sentence-transformers/flashrank/tree-sitter.
- mcp_server/doctor.py — adds subcommand dispatch. `cortex-doctor` (no
  args) preserves legacy full-setup verification; `cortex-doctor mcp`
  routes to doctor_mcp.run_mcp.
- tests_py/test_doctor_mcp.py + tests_py/scripts/test_launcher_resolution.py
  — 49 new tests covering happy path + every named failure mode (missing
  plugins.json, missing key, stale installPath, missing/broken launcher,
  unset/invalid DATABASE_URL, env-var-set/unset/invalid for launcher
  resolution).
- pyproject.toml + .claude-plugin/marketplace.json → 3.15.2.
- CHANGELOG.md — entry documenting the Discord report and the fix.

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

* fix(deps): pin tree-sitter-language-pack <1.7 + ruff format CI fix

Two CI gates failing on PR #22 — both are latent / dep-drift issues, not introduced by the v3.15.2 fixes themselves.

tree-sitter-language-pack 1.7.0+ changed Parser API; pip resolves >=0.24.0 to the latest (1.8.0 on CI right now), breaking 'parser.parse(...)' calls in tests_py/core/test_ast_*.py and tests_py/benchmarks/test_codebase_alteration.py with 'builtins.Parser has no attribute parse'. Pinning <1.7 keeps the contract that v3.15.2 was tested against. The latent break would also hit main on its next CI run; this commit protects both.

Lint failure on tests_py/scripts/test_mcp_json_contract.py was a stale ruff format from the parallel-agent merge.

---------

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

Author: cdeust

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent memory and cognitive profiling plugins for Claude Code",
-    "version": "3.15.1"
+    "version": "3.15.2"
   },
   "plugins": [
     {
       "name": "cortex",
       "source": "./",
       "description": "Persistent memory and cognitive profiling for Claude Code — thermodynamic memory with heat/decay, intent-aware retrieval, biological plasticity, codebase intelligence, and cognitive profiling. 47 MCP tools with enriched schemas. PostgreSQL + pgvector in CLI mode; automatic SQLite fallback in Cowork/sandboxed mode. Curated wiki (ADRs, specs, lessons) with audit-artefact filtering. Consolidate is set-based SQL batched — decay/plasticity/pruning run 100-500× faster on large stores. Workflow graph with caller-qualified CALLS chains rendering full method-to-method dependencies (native tree-sitter, no AP required). Side panel humanized for non-technical users. Ingests codebase analysis (ai-automatised-pipeline) and PRDs (prd-spec-generator) into wiki + memory + knowledge graph. Docker image available.",
-      "version": "3.15.1",
+      "version": "3.15.2",
       "author": {
         "name": "Clement Deust",
         "email": "admin@ai-architect.tools"

.mcp.json

@@ -3,8 +3,8 @@
     "cortex": {
       "command": "python3",
       "args": [
-        "-c",
-        "import json,os; p=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json')))['plugins']['cortex@cortex-plugins'][0]['installPath']; os.execvp('python3',['python3',os.path.join(p,'scripts','launcher.py'),'mcp_server'])"
+        "${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py",
+        "mcp_server"
       ],
       "env": {
         "DATABASE_URL": "postgresql://localhost:5432/cortex",

CHANGELOG.md

@@ -6,6 +6,37 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [3.15.2] - 2026-05-09
+
+### Fixed
+- **MCP startup robustness** — Discord user reported the Cortex MCP server
+  failing to start with no actionable error. Root cause: `.mcp.json` used a
+  fragile `python -c` one-liner that read `~/.claude/plugins/installed_plugins.json`
+  to dynamically resolve the install path. The wrapper swallowed all
+  launcher startup errors invisibly and broke under: (a) plugin upgrade
+  leaving stale `installPath`, (b) custom marketplace install names, (c)
+  `python3` not on PATH, (d) any `installed_plugins.json` shape change by
+  Claude Code. `.mcp.json` now uses `${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py`
+  — Anthropic's documented plugin substitution variable, already used by
+  every hook in this repo. The launcher self-orients via `__file__` so
+  manual installs continue to work.
+
+### Added
+- **`cortex-doctor mcp`** — new diagnostic subcommand for end-to-end MCP
+  startup checks. Tells the user *exactly* which check failed, what
+  command/path was tried, and the actual error string — no more silent
+  "✘ failed". Checks: python interpreter on PATH, `installed_plugins.json`
+  shape, `CLAUDE_PLUGIN_ROOT` env, launcher smoke probe (catches errors
+  the old `-c` wrapper hid), `DATABASE_URL`, critical Python deps. Use
+  `--json` for Discord-paste-friendly output.
+
+### Verification
+- 36 new tests added (`tests_py/test_doctor_mcp.py`,
+  `tests_py/scripts/test_launcher_resolution.py`); all pass.
+- Backward-compatible: `cortex-doctor` (no subcommand) preserves legacy
+  full-setup verification behaviour.
+- Platform-agnostic: no Windows/Mac-specific code paths.
+
 ## [3.15.1] - 2026-05-05
 
 ### Fixed

mcp_server/doctor.py

@@ -271,12 +271,29 @@ def _i10_config() -> Check:
 
 
 def run() -> int:
-    """Run all checks. Print a report. Return 0 on required-green, 1 otherwise.
-
-    Optional checks (``Check.optional=True``) warn on failure but do not
-    cause a non-zero exit. Only core-required checks (PG connection,
-    Python version, etc.) gate the exit code.
+    """Entry point. Dispatches to subcommand if given, else full check.
+
+    Subcommands:
+      (none)   Full setup verification (Python, PG, extensions, etc.)
+      mcp      MCP startup diagnostics (Discord-debug-friendly)
+               Flags:
+                 --json   Emit machine-readable JSON report
+                 --copy   Prepend a "paste me in Discord" header to the
+                          human output (useful for issue templates)
     """
+    argv = sys.argv[1:]
+    if argv and argv[0] == "mcp":
+        from mcp_server.doctor_mcp import run_mcp
+
+        flags = argv[1:]
+        json_output = "--json" in flags
+        copy_header = "--copy" in flags
+        return run_mcp(json_output=json_output, copy_header=copy_header)
+    return _run_full_check()
+
+
+def _run_full_check() -> int:
+    """Full setup verification (legacy `cortex-doctor` behaviour)."""
     checks = [c() for c in CHECKS]
     width = max(len(c.name) for c in checks) + 2