SAGE — Solver-Augmented Grounding Engine

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

Why SAGE Exists

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.

The Runtime Advantage

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.

What it does

Quick Start

1. Install

# 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/

2. Configure Claude Desktop

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 manual pip install required. If you have uv installed (brew install uv on macOS), uvx sage-solver-mcp fetches and runs SAGE automatically. If Claude Desktop cannot find uvx on your PATH, use the full path: "/opt/homebrew/bin/uvx" (macOS) or the output of which uvx.

Restart Claude Desktop and you will see the SAGE tools in the toolbar.

3. Try it

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"

MCP Tools

... View full README on GitHub