Skip to main content
Glama
sharabhshukla

Decisify

by sharabhshukla
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Decisify

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

Python 3.12+ FastMCP Strands Multi-Agent PySCIPOpt License: MIT Tests Passing

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

🌟 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.

Related MCP server: USolver

🏗️ 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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google OR-Tools server

    Jacck
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP-ORTools integrates Google's OR-Tools constraint programming solver with Large Language Models through the MCP, enabling AI models to: Submit and validate constraint models Set model parameters Solve constraint satisfaction and optimization problems Retrieve and analyze solution
    21
    MIT

  • USolver

    sdiehl
    A
    license
    B
    quality
    F
    maintenance
    A best-effort universal logic and numerical solver interface using MCP that implements the 'LLM sandwich' model to process queries, call dedicated solvers (ortools, cvxpy, z3), and verbalize results.
    7
    65
    Apache 2.0

  • MCP Optimizer

    mrugankpednekar
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables solving linear programming (LP) and mixed-integer linear programming (MILP) optimization problems through natural language, with built-in simplex and branch-and-cut solvers plus infeasibility diagnostics. Includes optional OR-Tools fallback for larger problems and supports parsing optimization problems from natural language descriptions.
    MIT