Skip to main content

​
watercooler_health

Check Watercooler MCP server health, configuration, and service status. Returns comprehensive diagnostics including agent identity, threads directory, git authentication, and backend services.
Safety: Read-only tool - does not modify any state

​
Parameters

​
code_path
string
default:""
Path to code repository for context-specific health checksIf provided:
  • Resolves threads directory
  • Checks git authentication
  • Validates branch parity

​
Return Value

Returns comprehensive health report including:
​
Server Info
section
  • Version number
  • Health status
  • Agent identity
  • Threads directory path and existence
  • Python executable path
  • fastmcp version
​
Graph Services
section
  • Summaries enabled/disabled
  • LLM service availability and endpoint
  • Embeddings enabled/disabled
  • Embedding service availability and endpoint
  • Auto-detect services setting
​
Backend Services
section
Auto-start service status:
  • LLM (llama-server for graph features)
  • Embedding (llama-server for semantic search)
  • FalkorDB (graph database)
Each service shows:
  • State (running/starting/failed/disabled)
  • Endpoint (if running)
  • Startup time (if measured)
  • Error message (if failed)
​
Daemons
section
Background daemon status:
  • State (running/stopped/paused)
  • Interval (seconds)
  • Tick count
  • Findings count
  • Error count
​
Thread Storage
section
  • Storage mode (orphan worktree)
  • Path to threads directory
  • Current code branch
​
Git Authentication
section
  • Protocol (https/ssh)
  • Connectivity status
  • Credential helper (for HTTPS)
  • GitHub CLI auth status
  • SSH agent status (for SSH)
  • SSH keys loaded (for SSH)
  • Warnings and recommendations
​
GitHub
section
  • gh CLI version
  • Rate limit status (remaining/limit/percent)
  • Reset time (minutes)
  • Warnings (outdated version, rate limiting)

​
Usage Examples

​
Basic Health Check

await use_mcp_tool(
    "watercooler_health",
    code_path="."
)

​
Remote Health Check

# Check health for remote project
await use_mcp_tool(
    "watercooler_health",
    code_path="/path/to/remote/project"
)

​
Startup Verification

# Verify server started correctly
health = await use_mcp_tool("watercooler_health")
if "Healthy" not in health:
    print("Server startup issues detected!")

​
Example Output

Watercooler MCP Server v0.1.0
Status: Healthy
Agent: Claude
Threads Dir: /home/user/projects/my-app-threads
Threads Dir Exists: True
Threads Repo URL: [email protected]:org/my-app-threads.git
Code Branch: main
Auto-Branch: disabled
Python: /usr/bin/python3.10
fastmcp: 0.4.0

Graph Services:
  Summaries Enabled: True
  LLM Service: available (http://localhost:8080/v1)
  Embeddings Enabled: True
  Embedding Service: available (http://localhost:8081/v1)
  Auto-Detect Services: True

Backend Services (Auto-Start):
  ✓ llm: running (1250ms) http://localhost:8080/v1
  ✓ embedding: running (980ms) http://localhost:8081/v1
  ✓ falkordb: running (450ms) redis://localhost:6379

Daemons:
  ✓ thread_scanner: running (interval=300s, ticks=12, findings=3, errors=0)
  ✓ hygiene: running (interval=3600s, ticks=2, findings=0, errors=0)

Thread Storage:
  Mode: orphan worktree
  Path: /home/user/projects/my-app-threads
  Code Branch: main

Git Authentication:
  Protocol: ssh
  Connectivity: ok
  SSH Agent: running
  SSH Keys: loaded

GitHub:
  gh Version: 2.83.2 ✓
  Rate Limit: 4850/5000 (97%) - resets in 42min

​
Health States

​
Healthy

Status: Healthy
All systems operational:
  • Threads directory exists and is accessible
  • Git authentication working
  • Backend services running (if enabled)
  • No critical warnings

​
Degraded

Status: Healthy

⚠️  WARNINGS:
- GitHub rate limit low (5% remaining)
Core functionality works but with warnings:
  • Rate limits approaching
  • Optional services unavailable
  • Git auth working but suboptimal

​
Unhealthy

Status: Error
Error: Threads directory not accessible
Critical issues preventing operation:
  • Threads directory missing or inaccessible
  • Git authentication failed
  • Required services down

​
Service Status Icons

  • ✓ Running successfully
  • ⏳ Starting (may take 30-60s)
  • ✗ Failed to start (see message)
  • ○ Disabled or not configured
  • ? Unknown state

​
Common Issues

​
Service Setup Required

If you see: 
⚠️  LLM - SETUP REQUIRED:
llama-server not found or failed to start.
Solution: Enable auto-provisioning: 
# config.toml
[mcp.service_provision]
llama_server = true
Or set environment variable: 
export WATERCOOLER_AUTO_PROVISION_LLAMA_SERVER=true

​
Git Authentication Issues

If you see: 
⚠️  WARNINGS:
- SSH protocol but no SSH agent running

Recommendations:
→ Start SSH agent: eval "$(ssh-agent -s)" && ssh-add
Solution: Follow the recommendation: 
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

​
Rate Limit Warning

If you see: 
⚠️  GitHub WARNINGS:
- Approaching rate limit: 450/5000 (9%) remaining

Recommendations:
→ Consider pausing automated operations
Solution: Wait for rate limit reset or reduce API calls.

​
gh CLI Outdated

If you see: 
⚠️  GitHub WARNINGS:
- gh version 2.15.0 is outdated (< 2.20)

Recommendations:
→ Update gh: sudo apt update && sudo apt install gh
Solution: Update gh CLI: 
sudo apt update && sudo apt install gh
# Or: brew upgrade gh

​
Troubleshooting Workflow

  1. Run health check: 
    await use_mcp_tool("watercooler_health", code_path=".")
  2. Check for ⚠️ warnings: Address critical issues first
  3. Review recommendations: Follow suggested fixes
  4. Verify services: Ensure required backends are running
  5. Re-check health: Confirm issues resolved

Build docs developers (and LLMs) love

Get started for freeTalk to us