SAGE grounds AI in mathematical truth. It is a local MCP server that gives Claude Desktop — and any MCP-compatible agent — the ability to formulate, solve, and certify mathematical optimization problems using production-grade open-source solvers.
Status: v0.1.3 — Alpha · Author: Peter Pragnakar Atreides
Large Language Models are probabilistic text generators. When you ask an LLM to allocate a budget, design a schedule, optimize a route, or balance a portfolio, it generates text that resembles a solution. No simplex method runs underneath. No branch-and-bound search. No constraint check. The model cannot prove optimality, certify feasibility, or — critically — declare with certainty that no feasible solution exists.
One of the most valuable outcomes in decision-making is a mathematically certified statement of infeasibility. It tells decision-makers their goals conflict, their assumptions are inconsistent, or their constraints must be renegotiated. LLMs have no native mechanism to produce this. SAGE provides it.
SAGE introduces a hybrid intelligence architecture: LLMs handle language and ambiguity; solvers handle optimality and feasibility. Each component does what it is best suited for.
LLMs operate as single-pass inference systems — token generation stops when the response is done. Optimization solvers work differently: they are inherently iterative and stateful, designed to run for minutes, hours, or days while continuously improving. At any point they can return the best solution found so far, a bound on the optimal objective, and a certificate of optimality or infeasibility.
This "anytime" property enables SAGE to:
- Decompose large problems using Benders decomposition, column generation, or Lagrangian relaxation
- Run long-horizon solves asynchronously while the LLM remains conversationally responsive
- Checkpoint, pause, and resume optimization without losing progress
The result: AI shifts from immediate but approximate to sustained and mathematically grounded.
| Capability | Detail |
|---|---|
| Problem types | LP, MIP, Portfolio Optimization (QP), Workforce Scheduling |
| Solvers | HiGHS (LP/MIP), OSQP (QP) |
| File I/O | Read/write Excel (.xlsx) and CSV |
| Infeasibility | IIS detection + ranked relaxation suggestions |
| Sensitivity | Dual values, reduced costs, allowable ranges |
| Explanation | Plain-language narration of every result |
# From PyPI (once published)
pip install sage-solver-mcp
# From source (development)
git clone https://github.com/pragnakar/Project_Sage
cd sage
pip install -e sage-solver-core/
pip install -e sage-solver-mcp/Find your config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the SAGE server:
{
"mcpServers": {
"sage": {
"command": "uvx",
"args": ["sage-solver-mcp"]
}
}
}What is
uvx? It is a command from the uv Python toolchain that runs a PyPI package ephemerally — no manualpip installrequired. If you have uv installed (brew install uvon macOS),uvx sage-solver-mcpfetches and runs SAGE automatically. If Claude Desktop cannot finduvxon your PATH, use the full path:"/opt/homebrew/bin/uvx"(macOS) or the output ofwhich uvx.
Restart Claude Desktop and you will see the SAGE tools in the toolbar.
Ask Claude:
"Solve this LP: maximize 3x + 5y subject to x + 2y ≤ 12, x ≤ 8, y ≤ 5, x,y ≥ 0"
Or with a file:
"Read examples/portfolio_5_assets.xlsx and solve it as a portfolio optimization"
| Tool | Description |
|---|---|
solve_optimization |
Solve LP / MIP / portfolio / scheduling from JSON |
read_data_file |
Read an Excel or CSV file and return a preview |
solve_from_file |
Read + solve + write results in one step |
explain_solution |
Narrate the most recent solve result |
check_feasibility |
Check feasibility; if infeasible, compute IIS |
generate_template |
Create a blank Excel template for a problem type |
suggest_relaxations |
Rank constraint relaxations for the last infeasible result |
Each example shows the user prompt, which tool is called, a representative input payload, and the output SAGE returns.
User prompt: I need to figure out how many full-time and part-time employees to schedule to minimize cost. Full-time costs $200/day and covers 8 hours, part-time costs $100/day and covers 4 hours. I need at least 40 hours covered each day and at most 6 full-time staff.
Tool: solve_optimization
{
"problem_type": "lp",
"name": "staffing",
"variables": [
{"name": "ft", "lb": 0, "ub": 6},
{"name": "pt", "lb": 0}
],
"constraints": [
{"name": "coverage", "expression": {"ft": 8, "pt": 4}, "sense": ">=", "rhs": 40}
],
"objective": {"sense": "minimize", "coefficients": {"ft": 200, "pt": 100}}
}Output: Optimal: ft=2, pt=6, cost=$1,000/day. The coverage constraint is binding. Sensitivity: each additional required hour costs $25.
User prompt: My shift schedule says workers need at least 3 people on Monday AND no more than 2 people total — is that solvable?
Tool: check_feasibility
{
"problem_type": "lp",
"name": "schedule_check",
"variables": [{"name": "workers", "lb": 0}],
"constraints": [
{"name": "min_staff", "expression": {"workers": 1}, "sense": ">=", "rhs": 3},
{"name": "max_staff", "expression": {"workers": 1}, "sense": "<=", "rhs": 2}
],
"objective": {"sense": "minimize", "coefficients": {"workers": 0}}
}Output: INFEASIBLE. Conflicting constraints: min_staff (≥3) and max_staff (≤2) are mutually exclusive. Suggestion: relax max_staff to ≥3 (+50%) or reduce min_staff to ≤2 (−33%).
User prompt: I have a portfolio spreadsheet with expected returns and a covariance matrix. Optimize it for a target return of 8% while minimizing risk.
Tools: read_data_file → solve_from_file
read_data_file output: Detected sheets: assets (5 rows, columns: ticker, expected_return), covariance (5×5 matrix). Preview looks correct.
solve_from_file output: Optimal allocation — AAPL: 32%, MSFT: 28%, GOOGL: 18%, BND: 22%, CASH: 0%. Portfolio variance: 0.0042 (σ=6.5%). Results written to portfolio_optimized.xlsx.
User prompt: Can you create a scheduling template I can fill in? Then after I solve it, give me a detailed explanation.
Step 1 — Tool: generate_template with problem_type: "scheduling"
Output: Template written to scheduling_template.xlsx with sheets: workers (name, availability, cost), shifts (name, start, end, required_count), instructions.
Step 2 — Tool: explain_solution with detail_level: "detailed"
Output: "The optimal schedule assigns Alice and Bob to the morning shift (cost: $480) and Carlos to the evening shift (cost: $220). The evening minimum-staffing constraint has a shadow price of $45 — each additional required worker increases cost by $45. The morning capacity constraint has 1 unit of slack."
User prompt: I want to buy whole units of 3 products to maximize profit, but I can only spend $500 and store 20 cubic feet. Product A: $80, 3 ft³, $120 profit. Product B: $50, 5 ft³, $70 profit. Product C: $120, 2 ft³, $200 profit.
Tool: solve_optimization (MIP with integer variables A, B, C; budget ≤ 500; storage ≤ 20; maximize 120A + 70B + 200C)
Tool: suggest_relaxations (called automatically on infeasible sub-problem)
Output: Optimal integer solution: A=2, B=0, C=3, profit=$840. If the budget constraint is binding, suggest_relaxations ranks options: relax budget by $20 (+4%) to $520, or drop 1 unit of C and add 1 unit of A for $760 profit within the original $500 limit.
| File | Problem | Result |
|---|---|---|
examples/portfolio_5_assets.xlsx |
Portfolio QP — 5 assets (equity + bonds) | Optimal allocation |
examples/nurse_scheduling.xlsx |
Scheduling MIP — 8 nurses, 3 shifts, 7 days | Infeasible: IIS computed |
examples/transport_routing.xlsx |
Transport LP — 3 warehouses → 5 stores | Optimal routes, $2,472 cost |
examples/blending_problem.xlsx |
Blending LP — 6 ingredients, nutrient constraints | Optimal blend, $23.47/100kg |
Project_Sage/
├── sage-solver-core/ # Pure optimization engine — solver, models, fileio, explainer
│ └── sage_solver_core/
│ ├── models.py # Pydantic models (LPModel, MIPModel, PortfolioModel, SchedulingModel)
│ ├── solver.py # HiGHS + OSQP solver adapters
│ ├── builder.py # JSON → SolverInput builders
│ ├── fileio.py # Excel/CSV read/write, template generation
│ └── explainer.py# Natural language solution narration + IIS explanation
├── sage-solver-mcp/ # Local MCP server (this package — v0.1)
├── sage-cloud/ # Cloud API (future — v0.2)
└── examples/ # Ready-to-use example files
Data flow:
Claude Desktop → stdio JSON-RPC → sage-solver-mcp → sage-solver-core → HiGHS/OSQP
↓
SolverResult + IIS + Sensitivity
Variables with continuous bounds, linear objective, linear constraints (<=, >=, =).
Same as LP but variables can be continuous, integer, or binary.
Markowitz mean-variance: minimize risk (quadratic) for a target return, with optional sector and weight constraints.
Assign workers to shifts over a planning horizon. Constraints: min/max workers per shift, rest periods, skill requirements.
| Phase | Focus |
|---|---|
| v0.1 (now) | LP, MIP, Portfolio QP, Scheduling — 7 MCP tools, local stdio server |
| v0.2 | sage-cloud FastAPI — remote deployment, async long-running solves |
| v0.3 | Simulation — Monte Carlo, discrete-event, stochastic programming |
| v1.0 | Decision Intelligence Platform — industry templates, solver marketplace |
The long-term ambition is a planetary-scale optimization fabric: interconnected, federated models that co-optimize transportation, energy, supply chains, and infrastructure across institutions — turning SAGE from a single-user tool into shared decision infrastructure.
See CONTRIBUTING.md for dev setup, test instructions, and branch conventions.
393 tests · 0 failures · sage-solver-core 0.1.3 · sage-solver-mcp 0.1.3
MIT — Copyright (c) 2026 Peter Pragnakar Atreides