# 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