<div align="center">

Decisify

Autonomous Mathematical Optimization & Multi-Agent Graphs via Model Context Protocol (MCP)

<p align="center"> <b>Decisify</b> transforms unstructured natural language operational problems into rigorously formulated, validated, and solved Mixed-Integer Linear Programming (MILP) models. Built on the <b>Strands Multi-Agent Graph</b> orchestration engine, <b>PySCIPOpt</b> solver, and <b>FastMCP</b>, Decisify brings autonomous, closed-loop Operations Research capabilities directly to your LLM chat assistants, IDEs, and agentic workflows. </p>

Key Features • Architecture • Quickstart • Running Server • Client Setup • Tool Catalog • Contributing

---

</div>

🌟 Key Features

• 🔄 Autonomous Closed-Loop Feedback Cycles: Specialized reviewer agents rigorously audit mathematical formulations, PySCIPOpt code syntax, and runtime solver status (optimal, infeasible, unbounded), automatically cycling back to upstream agents for self-correction.
• 🧩 Dual Operating Paradigm:
  • Modular MCP Tools: Call standalone micro-agents for individual tasks (e.g., query clarification, mathematical formulation, sandbox code execution).
  • Autonomous End-to-End Workflow: Execute the entire multi-agent graph deterministically from a single high-level prompt.
• 📐 Structured Pydantic Intermediate Representations: Outputs are strictly validated using Pydantic schemas (FormulationIR, ExecutableModelCode), eliminating fragile regex and markdown parsing errors.
• 🛡️ Subprocess Sandbox Execution: PySCIPOpt models execute in isolated, timeout-protected subprocess environments to ensure host safety and stability.
• 🐳 Zero-Configuration Docker Deployment: Pre-built Docker container bundled with Debian Slim, SCIP solver, and FastMCP transport support (stdio, sse, streamable-http).
• 🌐 Native MCP Compatibility: Seamlessly integrates with Claude Desktop, Cursor, VS Code (Cline/Roo-Code), LibreChat, and the official Model Context Protocol Inspector.

---

🏗️ Multi-Agent Architecture & Topology

Decisify organizes Operations Research modeling into a directed, cyclic multi-agent graph with specialized generator and reviewer personas. When an error or inconsistency is detected, the graph dynamically backtracks to the appropriate reasoning stage.

graph TD
    User([User / MCP Client]) --> MCP[Decisify FastMCP Server]
    
    subgraph "FastMCP Interface Layer"
        MCP --> Decomp[decompose_optimization_query]
        MCP --> Tools[Modular Agent Tools]
        MCP --> Sandbox[execute_pyscipopt_sandbox]
        MCP --> Workflow[run_end_to_end_workflow]
    end

    subgraph "Autonomous Multi-Agent Graph (Strands Engine)"
        ReqClar[Requirements Clarifier Agent] --> ReqRev[Requirements Reviewer Agent]
        ReqRev -- "Needs Clarification" --> ReqClar
        ReqRev -- "Requirements Validated" --> MathProp[Math Model Proposer Agent]
        
        MathProp --> MathRev[Math Model Reviewer Agent]
        MathRev -- "Formulation Errors" --> MathProp
        MathRev -- "Math Model Approved" --> CodeGen[PySCIPOpt Model Coder Agent]
        
        CodeGen --> CodeRev[Model Code Reviewer Agent]
        CodeRev -- "Syntax / Logic Issue" --> MathProp
        CodeRev -- "Code Approved" --> CodeExec[Sandbox Code Executor Agent]
        
        CodeExec --> ExecRev[Execution Reviewer Agent]
        ExecRev -- "Runtime / Infeasible Error" --> CodeGen
        ExecRev -- "Optimal Solution Found" --> Output([Validated Solution & Report])
    end

    Workflow --> ReqClar
    Tools -.-> ReqClar
    Tools -.-> MathProp
    Tools -.-> CodeGen
    Tools -.-> CodeExec

Self-Correction & Routing Logic

1. Requirements Phase: Requirements Clarifier structures fuzzy user requests into decision variables, sets, parameters, and constraints. Requirements Reviewer verifies completeness.
2. Formulation Phase: Math Model Proposer writes formal algebraic specifications (LaTeX/Formulation IR). Math Model Reviewer checks constraint consistency and objective sense.
3. Implementation Phase: PySCIPOpt Model Coder generates structured Python code with typed variables (C, I, B) and solver constraints. Model Code Reviewer inspects code quality and SCIP API compatibility.
4. Execution & Diagnostics Phase: Sandbox Code Executor executes the model in a subprocess sandbox with timeout limits. Execution Reviewer evaluates solver status and diagnoses infeasibilities or unbound solutions.

---

🚀 Quickstart

Prerequisites

• Python 3.12 or higher
• An OpenAI-compatible API key (OpenAI, OpenRouter, Azure AI Foundry, or local vLLM/Ollama)

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/your-org/decisify.git
cd decisify

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[dev]"

Using standard pip

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Environment Configuration

Configure your LLM provider credentials in a .env file or export them directly:

# For OpenAI / OpenRouter
export OPENAI_API_KEY="your-api-key"
export BASE_URL="https://openrouter.ai/api/v1"  # Optional override

# For Azure AI Foundry / Azure OpenAI
export BASE_URL="https://<your-resource-name>.openai.azure.com/openai/v1"
export OPENAI_API_KEY="your-azure-key"

---

🖥️ Running the MCP Server

Decisify supports stdio, SSE (Server-Sent Events), and Streamable HTTP transports.

1. Local CLI Execution

# Run over stdio (default)
fastmcp run server.py:mcp

# Run as SSE server on port 8000
fastmcp run server.py:mcp --transport sse --host 0.0.0.0 --port 8000

# Run as Streamable HTTP server on port 8000
fastmcp run server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000

2. Docker Container Execution

Pre-configured Docker container with built-in SCIP libraries and FastMCP:

# Build the image
docker build -t decisify:latest .

# Run with stdio transport
docker run -i --rm -e OPENAI_API_KEY="$OPENAI_API_KEY" decisify:latest

# Run with Streamable HTTP transport (Port 8000)
docker run -i --rm \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  decisify:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000

# Run with SSE transport (Port 8000)
docker run -i --rm \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  decisify:latest \
  --transport sse \
  --host 0.0.0.0 \
  --port 8000

---

🔌 Connecting to MCP Clients

Claude Desktop

Add Decisify to your claude_desktop_config.json:

Via Local uv

{
  "mcpServers": {
    "decisify": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/decisify/server.py:mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "BASE_URL": "https://openrouter.ai/api/v1"
      }
    }
  }
}

Via Docker

{
  "mcpServers": {
    "decisify": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "OPENAI_API_KEY",
        "decisify:latest"
      ]
    }
  }
}

---

Cursor & VS Code (Cline / Roo-Code)

Configure via your IDE's mcp.json or MCP settings panel:

For SSE / Streamable HTTP:

{
  "mcpServers": {
    "decisify": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

For stdio:

{
  "mcpServers": {
    "decisify": {
      "command": "fastmcp",
      "args": ["run", "/absolute/path/to/decisify/server.py:mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

---

LibreChat

Add to your librechat.yaml:

mcpServers:
  decisify:
    type: sse
    url: "http://localhost:8000/sse"

---

MCP Inspector (Interactive Web UI)

Debug and inspect tools, resources, and prompts:

npx @modelcontextprotocol/inspector

1. Open the inspector in your browser.
2. Select Transport: SSE (or Streamable HTTP).
3. Connect to http://localhost:8000/sse (or http://localhost:8000/mcp).

---

📦 MCP Catalog: Tools, Resources & Prompts

🛠️ Modular Tools

Tool Name	Type	Description
decompose_optimization_query	Decomposer Agent	Breaks open-ended optimization queries into modular tool steps.
clarify_requirements	Generator Agent	Extracts structured sets, parameters, variables, bounds, and constraints.
review_requirements	Reviewer Agent	Validates requirements completeness and structural integrity.
formulate_math_model	Generator Agent	Generates formal algebraic MILP equations and Formulation IR.
review_math_model	Reviewer Agent	Checks formulation validity, constraint dimensions, and linearity.
generate_model_code	Generator Agent	Generates typed PySCIPOpt Python code complying with ExecutableModelCode.
review_model_code	Reviewer Agent	Audits PySCIPOpt code for syntax, variable types, and solver methods.
execute_model_code	Generator Agent	Executes PySCIPOpt model code via the isolated execution sandbox.
review_execution_result	Reviewer Agent	Evaluates solver outputs, objective values, feasibility, and bounds.
execute_pyscipopt_sandbox	Execution Runner	Isolated subprocess runner executing PySCIPOpt code with timeout protection.
run_end_to_end_workflow	Autonomous Graph	Runs the complete cyclic multi-agent graph with self-correction loops.

---

📚 MCP Resources

URI	MIME Type	Description
optimization://catalog	text/markdown	Full reference catalog of tools, agents, schemas, and usage examples.
optimization://workflow-topology	text/vnd.mermaid	Mermaid diagram of the multi-agent graph with cyclic review loops.
optimization://schema/executable-code	application/json	JSON Schema for ExecutableModelCode structured code objects.
optimization://schema/formulation-ir	application/json	JSON Schema for FormulationIR mathematical formulation objects.

---

💬 Built-in Prompt Templates

Prompt Template	Arguments	Purpose
clarify_problem	problem_description	Guides user through structured requirements extraction for an optimization query.
formulate_optimization_model	specification	Guides the formulation of sets, parameters, variables, and constraints.
implement_pyscipopt_code	math_formulation	Directs the generation of clean, structured PySCIPOpt Python code.
audit_optimization_model	formulation, code	Performs a dual-stage mathematical and code correctness audit.
diagnose_execution_error	code, execution_output	Diagnoses runtime errors, solver infeasibility, or unbounded objective values.

---

🧪 Development & Testing

Decisify features a comprehensive test suite covering schema serialization, agent tool registration, controller condition transitions, and isolated sandbox execution.

# Run complete test suite with verbose output
pytest -v

# Run tests with coverage
pytest --cov=src --cov-report=term-missing

Project Structure

decisify/
├── src/
│   ├── agents.py         # 9 Strands modular agent definitions & prompts
│   ├── controllers.py    # Cyclic graph builder & conditional routing logic
│   ├── llms.py           # LLM client configuration & environment mappings
│   ├── models.py         # Pydantic schemas (FormulationIR, ExecutableModelCode)
│   ├── server.py         # FastMCP server registration (tools, resources, prompts)
│   └── tools.py          # Subprocess sandbox code execution runner
├── tests/
│   ├── test_agents.py       # Agent definition and tool binding tests
│   ├── test_controllers.py  # Graph topology, condition evaluation & routing tests
│   ├── test_models.py       # Pydantic schema validation & serialization tests
│   ├── test_server.py       # FastMCP tools, resources & prompt template tests
│   └── test_tools.py        # Sandbox execution & code extraction tests
├── Dockerfile            # Container definition with SCIP and FastMCP
├── pyproject.toml        # Build configuration, dependencies & metadata
├── server.py             # Server export entrypoint
├── CONTRIBUTING.md       # Contribution guidelines
└── LICENSE               # MIT License

---

🤝 Contributing

Contributions are warmly welcomed! Please read our CONTRIBUTING.md for details on code style, pytest guidelines, adding new agents, and submitting pull requests.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.