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)

Installation

1. Clone or extract the project

   cd reasoning_engine_mcp_demo
   

2. Create virtual environment

   python -m venv .venv
   
   # Windows
   .venv\Scripts\activate
   
   # Linux/Mac
   source .venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set API key

   # 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

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

python -m mcp.claude_agent --question "Your question here"

Option 3: HTTP API Server

# Start server
python mcp_api_server.py

# Server runs on http://localhost:8000
# API docs: http://localhost:8000/docs

API Example:

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:

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

# 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