Logic-LM MCP Server
A Model Context Protocol (MCP) server that provides symbolic reasoning capabilities using Logic-LM framework and Answer Set Programming (ASP).
Attribution
This implementation is inspired by and builds upon the Logic-LLM framework:
Original Research:
This MCP server adapts the Logic-LLM approach for integration with Claude Code and other MCP clients, providing LLM-collaborative symbolic reasoning through Answer Set Programming.
🚀 Quick Start
Prerequisites
Installation
Choose your preferred installation method:
Option 1: Install from PyPI (Recommended) ✅ LIVE ON PYPI
# Install with pip
pip install logic-lm-mcp-server
# Or install with uv (10-100x faster)
uv pip install logic-lm-mcp-server
📦 Package URL: https://pypi.org/project/logic-lm-mcp-server/
Option 2: Install with Clingo solver (for full functionality)
# Install with optional solver
pip install logic-lm-mcp-server[solver]
# Or with uv
uv pip install logic-lm-mcp-server[solver]
Option 3: Development Installation
git clone https://github.com/stevenwangbe/logic-lm-mcp-server.git
cd logic-lm-mcp-server
pip install -e .
Test Installation
Integration with Claude Code
After installing the package, add it to your Claude Code configuration:
Method 1: Using the console command (after PyPI installation)
claude mcp add logic-lm-mcp logic-lm-mcp
Method 2: Manual configuration
Edit ~/.config/claude/claude_desktop_config.json (create if it doesn't exist):
{
"mcpServers": {
"logic-lm": {
"command": "logic-lm-mcp"
}
}
}
Restart Claude Code to load the new MCP server.
- Test the integration:
Try these commands in Claude Code:
Check Logic-LM server health
Translate this logic problem to ASP: "All birds can fly. Penguins are birds. Can penguins fly?"
Alternative Integration (Other MCP Clients)
For other MCP-compatible tools, start the server manually:
The server will run on stdio and provide these tools:
get_asp_guidelines - Get ASP translation guidelinestranslate_to_asp_instructions - Get problem-specific ASP guidanceverify_asp_program - Execute ASP programs with Clingocheck_solver_health - Verify system health
Overview
Logic-LM MCP Server converts natural language logical problems into Answer Set Programming (ASP) format, solves them using the Clingo solver, and returns human-readable results. It provides a three-stage reasoning pipeline: Problem Formulation → Symbolic Reasoning → Result Interpretation.
Features
- Natural Language Input: Convert English logical problems to formal representations
- ASP-Based Reasoning: Uses Answer Set Programming for robust logical inference
- Clingo Integration: Leverages the Clingo ASP solver for symbolic reasoning
- Self-Refinement: Iterative improvement of solutions through multiple reasoning passes
- Template Library: Reusable ASP patterns for common logical structures
- Fallback Handling: Graceful degradation when solver components unavailable
- FastMCP Integration: Modern MCP server implementation with type safety
1. get_asp_guidelines
Get comprehensive ASP translation guidelines (cached for efficiency).
Parameters: None
Returns: Complete ASP Logic Translation Guidelines document with comprehensive instructions for translating natural language into Answer Set Programming format.
2. translate_to_asp_instructions
Get lightweight instructions for translating a specific natural language problem to ASP.
Parameters:
problem (string, required): Natural language logical problem to translate
Example:
{
"problem": "All cats are mammals. Fluffy is a cat. Is Fluffy a mammal?"
}
Response:
{
"success": true,
"solution": "TRANSLATE TO ASP: All cats are mammals...\n\nINSTRUCTIONS:\n1. Call get_asp_guidelines() for complete patterns\n2. Analyze logical structure...",
"confidence": 1.0,
"method": "lightweight_translation_instructions",
"metadata": {
"problem_length": 58,
"guidelines_cached": false,
"next_steps": ["Call get_asp_guidelines() if needed", "Generate ASP code", "Call verify_asp_program()"]
}
}
3. verify_asp_program
Directly verify and solve an ASP program using the Clingo solver.
Parameters:
program (string, required): ASP program code to verify and solvemax_models (integer, 1-100, default: 10): Maximum number of models to find
Example:
{
"program": "% Facts\ncat(fluffy).\n\n% Rule: All cats are mammals\nmammal(X) :- cat(X).\n\n% Query\n#show mammal/1.",
"max_models": 10
}
4. check_solver_health
Check Logic-LM server and Clingo solver health status.
Returns:
- Server status and component initialization status
- Clingo availability and version information
- System capabilities and configuration details
- Basic functionality test results
Architecture
Core Components
- LogicFramework: Main reasoning orchestrator
- ClingoSolver: ASP solver interface and management
- ASPTemplateLibrary: Reusable logical pattern templates
- FastMCP Integration: Modern MCP server implementation
Processing Pipeline
Natural Language Input
↓
LLM Translation Instructions (Problem-specific guidance)
↓
ASP Program Generation (LLM-driven with guidelines)
↓
Clingo Solver Execution
↓
Model Interpretation (Symbolic results)
↓
Human-Readable Output
Dependencies
- Python 3.8+: Core runtime environment
- FastMCP 2.0+: Modern MCP server framework
- Pydantic 2.0+: Input validation and type safety
- Clingo 5.8.0+: ASP solver (automatically detects if missing)
Installation
Option 1: Using pip
pip install -r requirements.txt
Option 2: Manual installation
pip install fastmcp>=2.0.0 pydantic>=2.0.0 clingo>=5.8.0
Option 3: Development setup
git clone <repository-url>
cd logic-lm-mcp-server
pip install -e .
Configuration
The server automatically handles:
- Clingo solver installation detection
- Template library loading
- Environment-specific optimizations
- Error recovery and fallback modes
Environment Variables
- No environment variables required
- Server runs with sensible defaults
Usage Examples
Basic Logical Reasoning
Input: "If it's raining, then the ground is wet. It's raining. Is the ground wet?"
Output: "Yes, the ground is wet. This conclusion follows from modus ponens..."
Syllogistic Reasoning
Input: "All birds can fly. Penguins are birds. Can penguins fly?"
Output: "Based on the given premises, yes. However, this conflicts with real-world knowledge..."
Set-Based Logic
Input: "All members of set A are in set B. X is in set A. Is X in set B?"
Output: "Yes, X is in set B. This follows from set inclusion transitivity..."
Testing
Basic Functionality Test
Test MCP Integration
# Test with Claude Code
claude mcp get logic-lm
Error Handling
- Clingo Unavailable: Provides informative error messages with installation guidance
- Invalid ASP Programs: Syntax checking with detailed error messages
- Solver Timeouts: Graceful handling of complex problems
- Resource Constraints: Memory and time limit management
- Simple Problems: 50-200ms response time
- Complex Reasoning: 200-1000ms with self-refinement
- Memory Usage: ~25MB base + ~1MB per concurrent request
- Concurrent Support: Multiple simultaneous reasoning requests
Troubleshooting
Common Issues
- "No module named 'pydantic'" or similar
- Install dependencies:
pip install -r requirements.txt
- "Clingo not available"
- Install Clingo:
pip install clingo - Server will run with limited functionality if Clingo is missing
- Server fails to start
- Check Python version:
python --version (requires 3.8+) - Test installation:
logic-lm-mcp --help
- MCP connection issues
- Verify MCP server configuration:
claude mcp get logic-lm - Check installation:
logic-lm-mcp --help
Getting Help
- Test installation:
logic-lm-mcp --help - Check the health endpoint: use
check_solver_health tool - Enable debug traces: set
include_trace=true in requests
FAQ - Common Setup Errors
"Missing required dependencies" on startup
Error:
❌ Missing required dependencies:
- fastmcp>=2.0.0
- pydantic>=2.0.0
Cause: Dependencies not properly installed or virtual environment not activated.
Solution:
# Option 1: Use virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt
# Option 2: Install globally
pip install -r requirements.txt
# Option 3: Use venv python directly
venv/bin/python start_server.py
"ModuleNotFoundError: No module named 'fastmcp'"
Error:
Traceback (most recent call last):
File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'fastmcp'
Cause: Virtual environment not properly activated or dependencies not installed.
Solution:
# Clean installation
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
"ModuleNotFoundError: No module named 'pydantic'"
Error:
ModuleNotFoundError: No module named 'pydantic'
Cause: Missing core dependency, often from incomplete installation.
Solution:
pip install pydantic>=2.0.0
# Or reinstall all dependencies
pip install -r requirements.txt
Virtual environment using system Python instead of venv Python
Error: Virtual environment is using the system Python instead of the isolated venv Python.
Symptoms:
- Packages installed globally instead of in venv
- Permission errors during package installation
which python shows system path after activation- Inconsistent behavior between development and production
Causes:
- Incorrect virtual environment activation
- Shell aliases overriding PATH (alias python, alias python3)
- Corrupted virtual environment
- PATH configuration issues
Solutions:
Option 1: Verify and fix activation
# Check if activation worked properly
source venv/bin/activate
which python # Should show venv/bin/python, not /usr/bin/python
# If still showing system python, check for aliases
alias python
alias python3
# Remove problematic aliases
unalias python
unalias python3
Option 2: Use explicit venv path (most reliable)
# Instead of relying on activation, use direct paths
venv/bin/python -c "import sys; print(sys.executable)"
venv/bin/pip install package-name
# For our package specifically
venv/bin/python -c "from logic_lm_mcp import LogicFramework; print('✅ Works!')"
Option 3: Recreate virtual environment
# Clean recreation if venv is corrupted
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
which python # Verify it shows venv/bin/python
pip install logic-lm-mcp-server
Option 4: Use absolute paths in shell
# For Linux/Mac
/full/path/to/venv/bin/python script.py
# For Windows
C:\full\path\to\venv\Scripts\python.exe script.py
"Clingo not available" but everything else works
Error:
"clingo_available": false
Cause: Clingo ASP solver not installed.
Solution:
# Option 1: Via pip
pip install clingo>=5.8.0
# Option 2: Via conda
conda install -c conda-forge clingo
# Option 3: Check installation
python -c "import clingo; print('Clingo available')"
Error: MCP connection fails or tools not found.
Cause: Server not properly configured in Claude Code.
Solution:
- Verify server is running:
python start_server.py - Check Claude Code MCP configuration
- Restart Claude Code if needed
- Use absolute paths in configuration
Python version compatibility issues
Error:
SyntaxError: invalid syntax
Cause: Python version < 3.8.
Solution:
# Check Python version
python --version # Must be 3.8+
# Use specific Python version
python3.8 -m venv venv
# or
python3.9 -m venv venv
Background process conflicts
Error: Server won't start, port already in use.
Cause: Previous server instance still running.
Solution:
# Kill existing processes
pkill -f start_server.py
pkill -f logic-lm
# Or find and kill specific process
ps aux | grep start_server
kill <process_id>
File permission errors
Error:
PermissionError: [Errno 13] Permission denied
Cause: Insufficient file permissions.
Solution:
# Fix permissions
chmod +x start_server.py
chmod -R 755 src/
# Or run with appropriate permissions
sudo python start_server.py # Not recommended
Import path issues
Error:
ModuleNotFoundError: No module named 'src'
Cause: Python can't find local modules.
Solution:
# Run from project root directory
cd /path/to/logic-lm-mcp-server
python start_server.py
# Or use absolute imports
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
Cache or old dependency conflicts
Error: Server uses old logic after code changes.
Cause: Python bytecode cache or old dependencies.
Solution:
# Clear Python cache
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -name "*.pyc" -delete
# Reinstall dependencies cleanly
rm -rf venv/
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Restart Claude Code
Memory or resource issues
Error: Server crashes or becomes unresponsive.
Cause: Insufficient system resources.
Solution:
- Close other applications to free memory
- Use smaller
max_models parameter in requests - Check system requirements (25MB base memory)
- Monitor server logs for resource warnings
Development
Project Structure
logic-lm-mcp-server/
├── src/
│ ├── __init__.py # Package initialization
│ ├── logic_lm_mcp/
│ │ ├── __init__.py # Package initialization
│ │ ├── main.py # FastMCP server implementation
│ │ ├── logic_framework.py # Core Logic-LM framework
│ │ └── asp_templates.py # ASP template library
├── pyproject.toml # Modern Python packaging
├── requirements.txt # Python dependencies
├── start_server.py # Development server startup
└── README.md # This documentation
Adding New Templates
- Edit
src/logic_lm_mcp/asp_templates.py - Add new template to
_initialize_templates() method - Test with
logic-lm-mcp --help and MCP tools
Extending Logic Framework
- Edit
src/logic_lm_mcp/logic_framework.py - Add new reasoning methods to
LogicFramework class - Update FastMCP tools in
src/logic_lm_mcp/main.py
Resources
ASP Templates
The server provides access to ASP templates via MCP resources:
asp-templates://list - List all available templatesasp-templates://info/{template_name} - Get template informationasp-templates://template/{template_name} - Get template code
Available Templates
- universal: Universal quantification (All X are Y)
- conditional: Conditional rules (If X then Y)
- syllogism: Basic syllogistic reasoning
- existential: Existential quantification (Some X are Y)
- negation: Negation patterns (No X are Y)
- set_membership: Set membership and relationships
- transitive: Transitive relationships
License
MIT License - See LICENSE file for details.
Support
For issues, feature requests, or questions about Logic-LM reasoning capabilities, please:
- Test installation:
logic-lm-mcp --help - Check the troubleshooting section above
- Open an issue in the repository with:
- Python version
- Operating system
- Error messages
- Installation method used (pip/uv)