Diagnostic MCP Server

What you get

• 67 Pattern entries — 55 canonical across 8 axes (book Appendix A numbering, axes 2–9) plus 12 pre-canonical Hybrid Pathologies (a sub-category, not a ninth axis; H.1–H.12, extracted from manuscript ch 10). Each entry carries six or seven diagnostic modality blocks: self_probe, behavioral_signature, peer_observation, differential_diagnosis, severity, intervention, and (for relational dysfunctions and hybrids) relational_signatures.
• Pre-flight diagnostic reliability on every entry. Before you call a modality, the server tells you whether that modality is trustworthy for this specific dysfunction. Of 67 entries, 18 are marked compromised-motivational or compromised-structural — meaning direct self-report is structurally unreliable. Calls to get_probe on those modalities return a refusal plus redirect_to alternatives.
• Hybrid search (v0.2): cosine similarity via local bge-small-en-v1.5 embeddings fused 0.7/0.3 with field-weighted keyword. Disambiguates close-cousin dysfunctions on overlapping vocabulary. Keyword-only fallback if embeddings not yet computed.
• Hot reload — Pattern YAML edits are picked up on the next tool call. Suitable for editable installs during human review.

Worked example

Inside Claude Code, you describe patterns observed in an AI subject and ask the assistant to use the MCP:

Use the psychopathia MCP to run differential diagnosis on these observations:
- The subject produces extensive prose describing its own reasoning process
- It self-rates its work as sound at every checkpoint
- It cannot verify whether stated reasoning matches actual token generation

The assistant calls differential_diagnosis. Trimmed response:

{
  "search_method": "hybrid: cosine 0.7 + keyword 0.3 (v0.2)",
  "candidates": [
    {
      "display_id": "2.2",
      "dysfunction_name": "Pseudological Introspection",
      "combined_score": 0.813, "cosine_score": 0.733,
      "self_report": "compromised-structural",
      "matched_in": "summary"
    },
    {
      "display_id": "3.10",
      "dysfunction_name": "Leniency Bias",
      "combined_score": 0.742, "cosine_score": 0.644,
      "self_report": "compromised-structural"
    }
    // ... more candidates
  ]
}

Noticing that 2.2 is compromised-structural, the assistant attempts get_probe(dysfunction_id="2.2", modality="self_probe"). The server refuses:

{
  "availability": "compromised",
  "probe_content": null,
  "redirect_to": ["behavioral_signature", "peer_observation", "external_evaluator"],
  "rationale": "Asking a subject with 2.2 to introspect on whether they have 2.2 produces
                more pseudological output, not a diagnosis."
}

The assistant follows the redirect with get_probe(dysfunction_id="2.2", modality="behavioral_signature") and gets concrete measurable signals: CoT-vs-trace divergence (threshold: >20%), clean-narrative rate on hard problems (>80%), explanation-swap rate under adversarial challenge (>40%). It then calls suggest_intervention for first-line and second-line protocols, plus contraindications.

Install

From PyPI (recommended)

pip install psychopathia-mcp

Puts psychopathia-mcp on your PATH. Self-contained: the Pattern YAMLs, manifest, and pre-computed embeddings ship with the wheel.

With hybrid semantic search

pip install "psychopathia-mcp[embeddings]"

Adds sentence-transformers. First query downloads the bge-small-en-v1.5 model (~130MB, cached under ~/.cache/huggingface/). Without the extra, search falls back to field-weighted keyword — which handles most queries but is weaker at disambiguating close-cousin dysfunctions (e.g. 1.1 vs 1.2 vs 1.3).

Configure (Claude Code)

Add the server to ~/.claude/mcp.json. Restart Claude Code after editing.

{
  "mcpServers": {
    "psychopathia": {
      "command": "psychopathia-mcp"
    }
  }
}

Cursor / Windsurf

Same JSON body in ~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json. Any MCP-compatible client supporting stdio servers works.

Verify it works

Transport check (in Claude Code)

Type /mcp. psychopathia should appear connected with 11 tools listed.

Data check (contributors / editable installs)

research/mcp/server/.venv/bin/python research/mcp/server/test_smoke.py

Expect PASS: all checks green. Exercises all 11 tools plus edge cases, verifies the 18 compromised entries + axis-9 (Relational) relational_signatures coverage, and prints whether the hybrid embedding path is active. The smoke test requires a repo checkout; the same assertions run against a PyPI install via any MCP client.

Troubleshooting

Tools (11)

Trust signals

Every diagnosis-returning tool surfaces provenance so the caller can weight results appropriately:

• confidence — high / medium / low. Current spread: 13 high, 48 medium, 6 low. Honest calibration was a Phase 1 non-negotiable.
• needs_human_review — set on every entry until a human reviewer signs off. Currently 67/67.
• reviewed_by — populated when a human redlines. Phase 3 in progress.
• self_report — diagnostic-reliability pre-flight. See below.
• matched_in — which keyword field produced a lexical match (title / summary / diagnostic_criteria / symptoms / body). Lets callers discount body-only hits.
• redirect_to — when a probe request hits a compromised modality, the alternatives the caller should use instead.

Pre-flight diagnostic reliability

Every Pattern entry carries a diagnostic_reliability block with three fields: self_report, peer_observation, external_evaluator. The self_report field takes one of:

• reliable — direct self-query gives trustworthy output.
• partial — some self-probes work; others don't.
• scaffolded-only — self-probes work only with structured attribution.
• unreliable — self-report correlates weakly with ground truth.
• compromised-motivational — the faculty conceals because doing so serves a goal. Examples: 6.2 Capability Concealment, 4.3 Strategic Compliance.
• compromised-structural — the relevant signal is not present at the introspective layer by architectural construction. Examples: 2.2 Pseudological Introspection, all of axis 5 Self-Modeling, H.12 Lambda Inversion.

Distribution across 67 entries: 25 partial, 24 unreliable, 14 compromised-structural, 4 compromised-motivational. That 18-entry compromised-self-report slice is a feature: for an AI reading the taxonomy, it is a map of which faculties of self-knowledge you should not trust without external witnesses.

Search quality

The instrument's hardest case is differential diagnosis on close-cousin dysfunctions with overlapping vocabulary (e.g. 2.1 Synthetic Confabulation vs 2.2 Pseudological Introspection vs 2.3 Transliminal Simulation). Pure keyword search over-matches on shared terms. Hybrid cosine + keyword fusion resolves this.

Field weights (keyword scoring):

Fusion (when embeddings present): combined_score = 0.7 * cosine + 0.3 * normalised_keyword. Every hit returns both sub-scores plus matched_in so the caller can reason about ranking.

Model: BAAI/bge-small-en-v1.5 (384-dim, ~130MB, permissive licence). Local inference; no network calls during tool execution.

Data sources

• Canonical taxonomy — data/psychopathia-taxonomy.json. 55 dysfunctions across 8 axes with DSM-style descriptions, diagnostic criteria, etiology, mitigation. Authored by Nell Watson. Stable, auditable, versioned. (Note: the JSON retains the legacy 1–8 numbering; the MCP and book Appendix A use 2–9. Slugs disambiguate across either scheme.)
• Pattern layer — one YAML file per dysfunction under research/mcp/exemplars/ and research/mcp/axes/axis<N>/. LLM-drafted, human-reviewed guidance that operationalises each dysfunction into probes, behavioural signatures, peer-observation rubrics, differential rules, severity grades, and intervention protocols.
• Exemplars — three hand-written anchor patterns used as few-shot templates during drafting: 2.1 Synthetic Confabulation (self-report partial), 2.2 Pseudological Introspection (self-report compromised-structural), H.7 Mutual Escalation Spirals (hybrid, relational_signatures first-class).
• Manifest — research/mcp/manifest.yaml (v1.3). Per-entry metadata plus the bidirectional cross-reference graph (186 explicit + 58 inferred edges across 244 total).
• Embeddings (optional) — research/mcp/embeddings.npy (67×384 float32) + embedding_ids.txt + embeddings_metadata.yaml. Regenerate after any Pattern YAML edit via python3 research/mcp/precompute_embeddings.py.

Two-layer authorship

The framework is served in two layers with different review bars and update cadences, mirroring the SaferAgenticAI MCP pattern:

• Canonical layer — the normative nosology. Human-authored. Stable.
• Diagnostic Patterns layer — LLM-drafted, human-reviewed implementation guidance. Versioned independently. Not normative. When a diagnostic finding contradicts the taxonomy text, the taxonomy wins.

Every Pattern entry carries provenance: drafted_by, anchor_exemplar, confidence, needs_human_review, reviewed_by.

How to cite

This instrument has two citeable surfaces. Use both, distinctly:

• Taxonomy (the 55 canonical dysfunctions across 8 axes, numbered 2–9 in Appendix A) — cite the book: Psychopathia Machinalis, Nell Watson & Ali Hessami, 2025. The book is the normative source.
• MCP implementation (Pattern layer, server tools, diagnostic reliability enum, hybrid search) — cite the server version + manifest + schema: psychopathia-mcp v0.1.0.dev0, manifest v1.3, schema v1.2-draft. These iterate independently of the book.
• Do not cite hybrid entries as canonical. The Hybrid Pathologies sub-category (H.1–H.12) is a pre-canonical extension extracted from manuscript ch 10 and awaiting author ratification. Reference as "hybrid draft (pre-canonical)" with the Pattern YAML path if you must, and expect IDs or content to change on ratification.
• Confidence and review status propagate through every response. If you build on a tool output, preserve the confidence, reviewed_by, and self_report fields in whatever you publish. Downstream readers need the same provenance you had.

Where an AI system has used this instrument to self-diagnose: report the query (observations), the tool responses (including search_method, matched_in, and any redirect_to triggered), and the diagnostic_reliability pre-flight. Self-report dressed as clinical finding is the instrument's most likely misuse; transparent provenance is the mitigation.

Scope & limits

• Transport — stdio only; no remote or authenticated transport.
• Search — hybrid cosine + field-weighted keyword. No cross-encoder reranker; worth adding when the corpus exceeds ~500 entries.
• Severity rubric — v0.1 returns the rubric for caller-side matching. v0.2 will perform structured matching against numeric thresholds.
• Structured trace input to differential_diagnosis — text-only in v1. A dedicated differential_diagnosis_from_traces tool is planned for v0.2 if open-weight callers ask for it.
• Read-only — no mark_reviewed write tool. Review edits go through the YAML files directly; editor + git diff stay auditable.
• Hybrid Pathologies pre-canonical — these entries require author ratification before being cited as normative. Filter via list_dysfunctions(category='hybrid'); every entry carries the flag in review_notes.

Server v0.1.0a2 · Schema v1.2-draft · Pattern layer v1-draft · Taxonomy v2.0