Anumana

io.github.sinhaKAN-rav0.2.1Updated Oct 5, 2026

Predict query cost, explain the plan, and rewrite it before you run it — 12 DB engines.

VerifiedSTDIODesktop onlyDeveloper ToolsAI & MLDatabases

Overview

AI-generated overview

Anumana lets an assistant preflight SQL and vector-search queries, estimating cost, risk tier, and scan strategy without executing them.

What it does
Anumana exposes tools that analyze a query before it runs: preflight_query reports a risk tier, rows scanned versus returned, scan strategy, and overhead flags; preflight_vector_search catches vector-search traps such as missing HNSW or IVFFlat indexes and oversized top_k; rewrite_query proposes a verified equivalent rewrite with before/after planner cost and selectivity-gated index suggestions; explain_query_working shows logical gather order and the physical plan; preflight_schema_only does static analysis against pasted CREATE TABLE DDL with no connection. It reads the real schema via EXPLAIN, never EXPLAIN ANALYZE, and covers 12 engines across 7 paradigms, with Postgres and SQLite…
When to use it
Use it when an AI coding agent writes SQL or RAG similarity searches and you want a cost and risk check before the query runs or reaches a pull request. It suits teams that want to catch brute-force vector scans, unbounded searches, or expensive plans early. It is not an NL-to-SQL tool or a database health dashboard.
Requirements
Runs locally over stdio, installed from PyPI as anumana-mcp (pip install anumana-mcp) or from source. Needs a Python runtime. Database access is configured through the ANUMANA_DSN read-only connection string, or ANUMANA_TARGETS for a multi-database setup; both are optional, and omitting them runs schema-only mode. ANUMANA_POLICIES optionally sets block, warn, or allow rules.
Before you install
ANUMANA_DSN and ANUMANA_TARGETS are secrets holding database connection strings; use a read-only role, since the server only issues EXPLAIN but read-only access is defence in depth. ANUMANA_POLICIES is open by default, so enforcement rules only apply if you configure them. Planner cost is unitless, not milliseconds, and every estimate carries an accuracy tier, so treat schema-only results as heuristic.

Installation

In SourceWeft

  1. Open Anumana in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Anumana

Know what your query will cost — before you run it. Inference-grade foresight for every query your AI writes.

Anumana is an MCP server that catches the costly query your AI coding agent just wrote — before it runs or reaches a PR. It rides inside Claude, Cursor, Windsurf, Codex, Kiro, or any MCP-compatible agent, reads your real schema via EXPLAIN (never EXPLAIN ANALYZE), and tells you — in plain English — how the query behaves and whether it'll hurt.

Its scope is the queries AI agents actually generate: text-to-SQL today, and RAG / vector search (pgvector) alongside it — because an agent writing a similarity search has no idea it just triggered a brute-force scan over every embedding. Anumana is the feedback loop the agent is missing.

It is not another NL→SQL tool and not a DB-health dashboard. It does one job: stop AI-written database code from silently rotting production.

What it does (the features)

ToolWhat it answers
preflight_query"Will this SQL query be costly?" — risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags. Without running it.
preflight_vector_search"Will this RAG similarity search be costly?" — catches the vector traps a plain SQL check misses: brute-force scan with no HNSW/IVFFlat index, top_k too large, unbounded search, metadata-filter/ANN recall loss.
rewrite_query"Make it cheaper." — a verified equivalent rewrite with before/after planner cost, plus index suggestions gated on selectivity (won't tell you to index a column when the filter matches most of the table). engine="pgvector" suggests an HNSW index.
explain_query_working"How does this run?" — two layers: the logical gather order (FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT) and the actual physical plan for your schema, step by step.
preflight_schema_only"I haven't given you DB creds yet." — static analysis against pasted CREATE TABLE DDL, no connection. Offline, zero-trust front door.

Engines (12, across 7 paradigms): Postgres and SQLite are live-tested; MySQL, pgvector, MongoDB, DynamoDB, FalkorDB, Cassandra, Redshift, BigQuery, Snowflake and ClickHouse ship as offline-verified, untested adapters that are promoted to live one at a time. Full matrix + cost signals in SUPPORTED_ENGINES.md. The adapter interface is in DESIGN.md.

The one honest rule

Postgres planner cost is unitless — not milliseconds (docs). Anumana never fakes a ~3.2s number. It reports rows scanned, scan strategy, a risk tier, overhead flags, and the cost-delta of a rewrite — all defensible, nothing invented. Every estimate carries an accuracy tier (UPPER_BOUND live, HEURISTIC schema-only).

Install

bash
pip install anumana-mcp          # once published to PyPI# or from source:pip install -e .

Then point your agent at it. The user installs it; the agent discovers the tools automatically on connect via the MCP tools/list handshake — there is no store to publish into.

Claude Desktop / Cursor / Windsurf / Kiro — mcpServers config block

jsonc
{  "mcpServers": {    "anumana": {      "command": "uvx",      "args": ["anumana-mcp"],      "env": { "ANUMANA_DSN": "postgres://readonly@localhost:5432/mydb" }    }  }}

Use a read-only Postgres role. Anumana only ever EXPLAINs, but read-only is defence in depth. Omit ANUMANA_DSN to run in schema-only mode (DDL in, no DB).

Try it with no database (30 seconds)

bash
python3 src/demo.py          # runs the engine on a canned plan, zero deps

Test against a real Postgres

bash
# a throwaway table, then:ANUMANA_DSN=postgres://localhost/mydb anumana-mcp

See src/live_test.py for a psql-backed harness that proves the real cost-delta and the selectivity gate on live data.

What's deliberately NOT here

No run_query (we never execute your SQL), no NL→SQL (the agent already does that), no DB-health reports, no dollar-billing. Staying narrow is the strategy.

License

MIT — see LICENSE.

Community & contact

Contributions welcome — see CONTRIBUTING.md and the Code of Conduct. Adding a database engine is the highest- leverage contribution; the adapter contract is small (SUPPORTED_ENGINES.md).

Source: README.md at commit 2694d0e

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.1LatestOct 5, 2026