Prolog Debug MCP Server

An MCP (Model Context Protocol) server that exposes SWI-Prolog as a debugging and diagnostic reasoning engine. Claude parses errors and symptoms, Prolog does logical deduction to find root causes.

Architecture

┌─────────────┐     stdio/SSE      ┌─────────────────┐
│   Claude    │ ◄─────────────────► │   MCP Server    │
│  (or LLM)   │      (MCP)         │   (Python)      │
└─────────────┘                    └────────┬────────┘
                                            │
                                            │ janus-swi
                                            ▼
                                   ┌─────────────────┐
                                   │   SWI-Prolog    │
                                   │  (swipl engine) │
                                   └─────────────────┘

Prerequisites

• SWI-Prolog 9.1.12+: Required by janus-swi

  # macOS
  brew install swi-prolog
  
  # Ubuntu/Debian
  sudo apt install swi-prolog
  

• Python 3.10+
• uv: For project management

Installation

cd prolog-debug-mcp
uv sync

Usage

Configure in Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "prolog-debug": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/prolog-debug-mcp", "python", "-m", "prolog_debug_mcp.server"]
    }
  }
}

Available Tools

Tool	Description
assert_dependency	Add a dependency: service depends on depends_on
assert_error	Record an observed error/symptom for a service
find_root_causes	Find all possible root causes for a service's errors
suggest_checks	Get suggested services to check based on dependencies
impact_analysis	Find all services affected if a given service fails
check_cycles	Check for dependency cycles involving a service
get_status	Get current session status (all services, dependencies, errors)
clear_session	Clear all asserted facts, start fresh
query	Run arbitrary Prolog query (advanced)

Example Session

User: "My web app is returning 500 errors. It talks to a postgres
       database and a redis cache. The redis pod is in CrashLoopBackOff."

Claude: Let me set up the dependency model and record the errors.

[Calls assert_dependency("webapp", "postgres")]
[Calls assert_dependency("webapp", "redis")]
[Calls assert_error("webapp", "500_error")]
[Calls assert_error("redis", "crashloopbackoff")]
[Calls find_root_causes("webapp")]

Result:
{
  "service": "webapp",
  "root_causes": [
    {"symptom": "crashloopbackoff", "path": ["webapp", "redis"]}
  ]
}

Claude: The root cause traces to Redis being in CrashLoopBackOff.
        The webapp depends on Redis, so when Redis crashes, the
        webapp returns 500s. Check the Redis pod logs for why
        it's crash-looping.

Testing

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_prolog.py

How It Works

Core Prolog Rules

The server uses a knowledge base with these key predicates:

• depends(Service, DependsOn) - Service depends on DependsOn
• error(Service, Symptom) - Service has an observed error/symptom
• root_cause(Service, Symptom, Path) - Traces errors through dependencies to find root causes
• has_cycle(Service) - Detects dependency cycles

Root Cause Logic

A root cause is found when:

1. A service has an error AND
2. Either it has no dependencies with errors (it's the root), OR
3. We can trace through dependencies to find a deeper error

This allows the system to answer "why is X failing?" by following the dependency chain to the actual source of the problem.

Tech Stack

Component	Choice	Rationale
MCP Framework	mcp (official SDK)	Official Python SDK for MCP
Prolog Bridge	janus-swi	5x faster than pyswip, C API, actively maintained
Prolog Engine	SWI-Prolog 9.1.12+	Required by janus, robust, good docs
Python	3.10+	Type hints, async support

License

CC0 1.0 Universal - Public Domain