/mcp-health - MCP Tool Health Check

Health check for all 9 CODITECT MCP tools. Verifies server availability, database connectivity, tool counts, and backend status.

System Prompt

EXECUTION DIRECTIVE: When /mcp-health is invoked, IMMEDIATELY execute the MCP health check script.

Usage

/mcp-health              # Full health check of all MCP tools
/mcp-health --quick      # Quick check (server availability only)
/mcp-health --json       # JSON output for automation
/mcp-health --verbose    # Detailed output with tool listings
/mcp-health --fix        # Attempt to fix common issues (restart servers, recreate indexes)
/mcp-health --risk <fn>  # Run risk assessment for a specific function

Execution

# Run the health check script
python3 ~/.coditect/scripts/mcp-health-check.py

# Quick mode
python3 ~/.coditect/scripts/mcp-health-check.py --quick

# JSON output
python3 ~/.coditect/scripts/mcp-health-check.py --json

# Verbose with tool listing
python3 ~/.coditect/scripts/mcp-health-check.py --verbose

# Fix mode
python3 ~/.coditect/scripts/mcp-health-check.py --fix

# Risk assessment shortcut
python3 ~/.coditect/scripts/mcp-health-check.py --risk process_payment

Health Categories

1. Server Availability

Server	Check	Expected
mcp-semantic-search	Import + stats	8 tools, databases accessible
mcp-call-graph	Import + stats	7 tools, tree-sitter available
mcp-impact-analysis	Import + stats	5 tools, call graph indexed
mcp-context-graph	Import + stats	17 tools, kg_nodes populated
mcp-cross-llm-bridge	Import + stats	15 tools
mcp-skill-server	Import + stats	18 tools, skills directory found
mcp-unified-gateway	Import + list	74 tools, 8 backends
mcp-backup	Import + validate	5 tools, GCS accessible
transcript-normalization	Import check	CLI available

2. Database Connectivity

Database	Check	Expected
org.db	Read kg_nodes count	> 0 nodes
org.db	Read decisions count	> 0 decisions
org.db	Read error_solutions count	> 0 solutions
sessions.db	Read messages count	> 0 messages
sessions.db	Read embeddings count	> 0 embeddings
call_graph.db	Read functions count	> 0 functions

3. Tool Counts

Backend	Expected Tools	Status
backup	5	Verify all 5 present
call_graph	7	Verify all 7 present
context_graph	17	Verify all 17 present
cross_llm	15	Verify all 15 present
git_status	5	Verify all 5 present
impact_analysis	5	Verify all 5 present
semantic_search	8	Verify all 8 present
skill_server	18	Verify all 18 present

4. Dependency Health

Dependency	Check	Required By
mcp SDK	import mcp	All MCP servers
sentence-transformers	import sentence_transformers	semantic-search
tree-sitter	import tree_sitter	call-graph
gcloud CLI	which gcloud	backup

Output Format

MCP Tool Health Check
=====================

Server Availability:
  [OK] mcp-semantic-search    8 tools, 143K embeddings
  [OK] mcp-call-graph         7 tools, 2,341 functions indexed
  [OK] mcp-impact-analysis    5 tools, risk engine ready
  [OK] mcp-context-graph      17 tools, 16,932 kg nodes
  [OK] mcp-cross-llm-bridge   15 tools, 5 providers configured
  [OK] mcp-skill-server       18 tools, 315 skills
  [OK] mcp-unified-gateway    74 tools, 8 backends
  [OK] mcp-backup             5 tools, GCS connected
  [OK] transcript-norm        CLI available

Database Health:
  [OK] org.db                 16,932 nodes, 7,118 edges, 1,856 decisions
  [OK] sessions.db            143K embeddings, 52K messages
  [OK] call_graph.db          2,341 functions, 5,892 edges

Dependencies:
  [OK] mcp                    v0.9.2
  [OK] sentence-transformers  v2.2.2
  [OK] tree-sitter            v0.21.3
  [OK] gcloud                 458.0.0

Summary: 9/9 servers healthy, 3/3 databases healthy, 4/4 dependencies OK

Error Output Examples

Server Availability:
  [OK] mcp-semantic-search    8 tools
  [!!] mcp-call-graph         FAILED: tree-sitter not installed
  [OK] mcp-impact-analysis    5 tools (degraded: call graph unavailable)
  ...

Fix suggestions:
  1. Install tree-sitter: pip install tree-sitter tree-sitter-python
  2. Re-index call graph: python3 ~/.coditect/tools/mcp-call-graph/server.py index ~/.coditect/scripts

Related Commands

• /health-check — General system health (Python, Node, Docker)
• /health-status — Agent health monitoring (ADR-110)
• /orient — Session orientation with tool discovery

Related Components

• Script: scripts/mcp-health-check.py
• Guide: docs/guides/MCP-TOOLS-QUICKSTART.md
• Tools: tools/mcp-*/ (all 9 MCP tools)
• Hooks: hooks/mcp-auto-risk-assessment.py, hooks/mcp-blast-radius-warn.py