MCP Calculation Engine Server

Model Context Protocol (MCP) server that exposes ARKEN's calculation engine /simulate/dynamic API for AI assistants like Claude.

Overview

This MCP server allows AI assistants to:

• Discover available process templates (dynamic flowsheets)
• View process details with parameter constraints
• Customize parameters within allowed bounds
• Run dynamic simulations with user-specific parameters
• Store and compare simulation runs
• Manage parameter version history (max 10 versions)

Architecture

User Request
     ↓
MCP Tool (e.g., simulate_process)
     ↓
Load process_template from MongoDB
     ↓
Load user_process_versions (if exists)
     ↓
Merge: template.base_payload + user.overrides
     ↓
Strip constraint metadata
     ↓
POST /simulate/dynamic
     ↓
Store result in simulation_runs
     ↓
Return to AI/User

Prerequisites

• Python 3.10 or higher
• ARKEN Calculation Engine running (default: http://localhost:8000)
• MongoDB 7.0+ running (default: localhost:27017)
• Docker and Docker Compose (for MongoDB setup)

Installation

1. Start MongoDB

Use the shared MongoDB instance from mcp_process_server:

cd ../mcp_process_server/docker
docker-compose up -d

2. Create virtual environment

cd mcp_calculation_engine_server
python3 -m venv venv
source venv/bin/activate

3. Install in development mode

pip install -e ".[dev]"

4. Configure environment

cp .env.example .env
# Edit .env with your MongoDB credentials

5. Seed process templates

python seed.py

MCP Tools

Note: Tools are prefixed with calc_ to avoid conflicts with mcp_process_server which handles sugar industry simulations.

Phase 1 - Core Simulation

Tool	Description
calc_list_processes	List all available dynamic flowsheet templates
calc_get_process	Get process details with current parameters (optionally merged with user customizations)
calc_simulate_process	Run dynamic flowsheet simulation with current parameters
calc_get_run	Retrieve a past simulation run
calc_list_runs	List all simulation runs for a user/process

Phase 2 - Parameter Editing & Validation

Tool	Description
get_editable_parameters	Get editable parameters with constraints and current values
validate_parameters	Validate parameter values before saving
edit_parameters	Save parameter modifications REMOVED - calc_simulate_process now auto-saves on success
get_user_parameters	Get user's saved parameter versions
switch_parameter_version	Switch to a different parameter version
compare_parameters	Compare parameters between versions or against template

Note: As of Phase 2 enhancement, inline parameters passed to calc_simulate_process are automatically saved as new versions when the simulation succeeds. The edit_parameters tool is no longer needed for the primary workflow.

MongoDB Collections

This server uses the shared arken_process_db database with calc_ prefixed collections:

Collection	Purpose
calc_process_templates	Dynamic flowsheet templates with constraints
calc_user_versions	User parameter overrides (max 10 versions)
calc_simulation_runs	Simulation results and history

Environment Variables

Variable	Description	Default
CALC_ENGINE_URL	Calculation engine base URL	http://localhost:8000
MONGODB_URI	MongoDB connection string	mongodb://localhost:27017
MONGODB_DATABASE	Database name	arken_process_db
MAX_VERSIONS	Max versions per user per process	10
LOG_LEVEL	Logging level	INFO

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "arken-calculation-engine": {
      "command": "/path/to/mcp_calculation_engine_server/venv/bin/python",
      "args": ["-m", "server"],
      "cwd": "/path/to/mcp_calculation_engine_server",
      "env": {
        "CALC_ENGINE_URL": "http://localhost:8000",
        "MONGODB_URI": "mongodb://arken_app:your_password@localhost:27017/arken_process_db?authSource=admin",
        "MONGODB_DATABASE": "arken_process_db"
      }
    }
  }
}

Configuration Notes

1. Replace paths: Update /path/to/ with your actual installation path
2. MongoDB credentials: Use the same credentials as in your .env file
3. Calculation Engine: Ensure the calculation engine is running before using Claude
4. Multiple servers: You can add multiple MCP servers in the same config file

Troubleshooting

Common Issues

1. "Database client not initialized" error

• Ensure MongoDB is running: docker ps | grep mongo
• Check MongoDB URI in .env file
• Verify credentials are correct

2. "Cannot connect to calculation engine" error

• Ensure calculation engine is running at the configured URL
• Check CALC_ENGINE_URL environment variable
• Test connectivity: curl http://localhost:8000/health

3. "Process not found" error

• Run seed script: python seed.py
• Check that templates exist in TestPayLoad/payloadwithconstrains/

4. Claude Desktop not seeing the server

• Restart Claude Desktop after config changes
• Check config file syntax (valid JSON)
• Verify Python path is correct: which python in your venv

5. Simulation timeout

• Complex simulations may take several minutes
• Default timeout is 600 seconds (10 minutes)
• Check calculation engine logs for progress

Checking Server Health

# Activate virtual environment
source venv/bin/activate

# Test MongoDB connection
python -c "from db_client import DatabaseClient; import asyncio; asyncio.run(DatabaseClient().health_check())"

# List seeded templates
python -c "
import asyncio
from db_client import init_db_client
async def main():
    db = await init_db_client()
    count = await db.process_templates.count_documents({})
    print(f'Templates: {count}')
asyncio.run(main())
"

Development

Run tests:

pytest

Run with coverage:

pytest --cov=. --cov-report=html

License

Proprietary - Arken AI