prolog-debug-mcp

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