# MCP Reasoning Engine with Claude Agent
A production-ready reasoning engine that combines Claude AI with Model Context Protocol (MCP) tools for structured reasoning across legal, health, and science domains.
## Features
- 🤖 **Claude Agent Integration**: Uses Anthropic's Claude API with tool use capabilities
- 🔧 **MCP Tools**: Three specialized tools for knowledge search, schema validation, and rubric evaluation
- 📚 **RAG Integration**: Knowledge base search across domain-specific documents
- ✅ **Schema Validation**: Ensures structured JSON output matches required schemas
- 📊 **Rubric Scoring**: Domain-specific evaluation with pass/fail thresholds
- 🌐 **HTTP API**: RESTful API for easy integration
- 🐳 **Docker Ready**: Containerized deployment support
## Architecture
```
┌─────────────────┐
│ HTTP API │ (Optional - mcp_api_server.py)
│ or Direct │
└────────┬────────┘
│
▼
┌─────────────────┐ ┌──────────────┐
│ Claude Agent │◄────►│ MCP Server │
│ claude_agent.py │ │ server.py │
└────────┬────────┘ └──────┬───────┘
│ │
▼ ▼
┌─────────────────┐ ┌──────────────┐
│ Anthropic API │ │ RAG Tools │
│ (Claude) │ │ Validators │
└─────────────────┘ └──────────────┘
```
## Quick Start
### Prerequisites
- Python 3.8+
- Anthropic API key ([Get one here](https://console.anthropic.com/))
### Installation
1. **Clone or extract the project**
```bash
cd reasoning_engine_mcp_demo
```
2. **Create virtual environment**
```bash
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate
```
3. **Install dependencies**
```bash
pip install -r requirements.txt
```
4. **Set API key**
```bash
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "your_api_key_here"
# Linux/Mac
export ANTHROPIC_API_KEY="your_api_key_here"
```
### Usage
#### Option 1: Direct Python Usage
```python
import asyncio
from mcp.claude_agent import ClaudeReasoningAgent
async def main():
agent = ClaudeReasoningAgent()
result = await agent.reason("Is a verbal promise enforceable?")
print(result)
asyncio.run(main())
```
#### Option 2: Command Line
```bash
python -m mcp.claude_agent --question "Your question here"
```
#### Option 3: HTTP API Server
```bash
# Start server
python mcp_api_server.py
# Server runs on http://localhost:8000
# API docs: http://localhost:8000/docs
```
**API Example:**
```bash
curl -X POST http://localhost:8000/reason \
-H "Content-Type: application/json" \
-d '{"question": "Is a verbal promise enforceable?"}'
```
## Project Structure
```
reasoning_engine_mcp_demo/
├── mcp/ # MCP server and agent
│ ├── server.py # MCP server with 3 tools
│ ├── claude_agent.py # Claude agent with MCP integration
│ └── DEPLOYMENT.md # Deployment guide
├── rag_docs/ # Knowledge base documents
│ ├── legal/ # Legal domain documents
│ ├── health/ # Health domain documents
│ └── science/ # Science domain documents
├── domains/ # Domain configurations
│ ├── domain_config.json # Domain routing config
│ ├── legal/rubric.json # Legal rubric
│ ├── health/rubric.json # Health rubric
│ └── science/rubric.json # Science rubric
├── schemas/ # JSON schemas
│ └── universal_reasoning_schema.json
├── validators/ # Validation modules
│ ├── schema_validator.py
│ └── rubric_validator.py
├── tools_rag.py # RAG search implementation
├── router.py # Domain routing
├── mcp_api_server.py # HTTP API server
├── requirements.txt # Python dependencies
└── README.md # This file
```
## MCP Tools
The MCP server exposes three tools:
1. **search_knowledge_base(query: str)**
- Searches RAG documents for relevant information
- Returns formatted results with source, title, and content
2. **validate_reasoning_schema(output_json: str)**
- Validates JSON output against the universal reasoning schema
- Returns validation status and errors
3. **evaluate_with_rubric(domain: str, output_json: str)**
- Evaluates reasoning output against domain-specific rubric
- Returns scores, pass/fail status, and human review flags
## Domains
The system supports three domains:
- **Legal**: Contract law, enforceability, legal reasoning
- **Health**: Medical information, symptoms, safety boundaries
- **Science**: Scientific reasoning, hypotheses, evidence evaluation
Each domain has:
- Domain-specific RAG documents
- Custom rubric for evaluation
- Keyword-based routing
## Configuration
### Environment Variables
- `ANTHROPIC_API_KEY` (required): Your Anthropic API key
- `MCP_PORT` (optional): HTTP API port (default: 8000)
- `MCP_HOST` (optional): HTTP API host (default: 0.0.0.0)
### Model Selection
Default model: `claude-3-haiku-20240307`
To use a different model:
```python
agent = ClaudeReasoningAgent(model="claude-3-sonnet-20240229")
```
Available models:
- `claude-3-haiku-20240307` (fast, cost-effective)
- `claude-3-sonnet-20240229` (balanced)
- `claude-3-opus-20240229` (most capable)
## API Documentation
When running the HTTP API server, visit:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
### Endpoints
- `GET /` - API information
- `GET /health` - Health check
- `GET /tools` - List available MCP tools
- `POST /reason` - Process a reasoning question
## Testing
```bash
# Test MCP server tools
python test_mcp_server.py
# Test with Claude
python test_mcp_server.py --with-claude
# Run all test cases
python run_all_tests.py
```
## Deployment
See `mcp/DEPLOYMENT.md` for detailed deployment instructions including:
- Local deployment
- Docker containerization
- Cloud deployment (AWS, Azure, GCP)
- Production best practices
## Security Notes
- **API Keys**: Never commit API keys to version control
- **Health Domain**: Always requires human review (configured in rubric)
- **Input Validation**: All inputs are validated before processing
- **HTTPS**: Use HTTPS in production environments
## Troubleshooting
### "ANTHROPIC_API_KEY not found"
- Ensure environment variable is set in your shell session
- Check that it's set before running Python scripts
### "ModuleNotFoundError: No module named 'mcp.claude_agent'"
- This is a namespace conflict with the `mcp` package
- The code handles this automatically via importlib
- If issues persist, check Python path configuration
### "Model not found" errors
- Verify your API key has access to the requested model
- Try using `claude-3-haiku-20240307` (most widely available)
## Support
For issues or questions, please refer to:
- `mcp/DEPLOYMENT.md` - Deployment guide
- `DEPLOYMENT_GUIDE.md` - Detailed deployment options
- API documentation at `/docs` endpoint
## Changelog
### Version 1.0.0
- Initial release
- MCP server with 3 tools
- Claude agent integration
- HTTP API server
- Domain routing and rubric evaluation
- Full test suite# MCP
# MCP
