Skip to main content
Glama

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)

Tool

What 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).


Related MCP server: mcp-database-tools

Install

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

{
  "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)

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

Test against a real Postgres

# 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).

Available Tools

9 tools
describe_schema_toolA

Read a database's REAL schema — tables/collections, columns/fields, INDEXES, and row counts — so you can write a grounded, cost-aware query BEFORE guessing. Call this FIRST when a user asks for data and you don't already know the schema; it tells you which columns are indexed so your query hits an index, not a full scan. READ-ONLY catalog access — never reads data rows. If the schema can't be read it returns need_from_user naming what to ask the user for. Pass target= in a multi-DB setup; combine with list_targets to find which DB has the data.

Inputs: target. Returns: result

explain_query_workingA

Explain in plain English HOW a query behaves — two layers: (1) the logical gather order (FROM -> WHERE -> GROUP BY -> HAVING -> SELECT -> ORDER BY -> LIMIT), why 'LIMIT 10' can still be slow; and (2) the actual physical plan the engine chose for THIS query, bottom-up. Call when a user asks why a query is slow or how it runs. Teaching tool. Pass target= in a multi-DB setup.

Inputs: sql (required), target. Returns: result

list_policiesA

List the operator's standing enforcement policies — the rules that can BLOCK or WARN on a query regardless of what you intend. Each has a name, scope (which target/engine), condition (risk tier and/or flag), and action (block/warn/allow). preflight_query and suggest_query already apply these and attach the verdict; call this to explain to a user WHY a query was blocked. No policies configured means open by default (nothing blocked).

Inputs: no named parameters. Returns: result

list_targetsA

List the databases Anumana is configured to analyse — each with its name, engine, and whether it's diagnosable. Call this FIRST in a multi-DB setup to see which target holds the data the user asked for, then pass target= to the other tools. In a single-DB setup you can omit target and the one database is used. Never returns connection strings or secrets.

Inputs: no named parameters. Returns: result

preflight_queryA

Before running ANY SQL query you (the agent) just wrote, check how costly it will be on the real schema — WITHOUT executing it. Returns a risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags (missing index, SELECT *, no LIMIT, N+1 / nested-loop blowup). EXPLAIN only — never runs the query. In a multi-DB setup pass target= (see list_targets). For similarity search use preflight_vector_search; with no DB use preflight_schema_only.

Inputs: sql (required), target. Returns: result

preflight_schema_onlyA

Analyse a query against pasted CREATE TABLE DDL with NO database connection — the zero-trust, offline front door. Call when the user gave you their schema (DDL) but not DB credentials. Catches SELECT *, missing LIMIT, un-indexed filter columns, LIKE '%...', functions on filtered columns. HEURISTIC only (no live counts) and says so. No target needed.

Inputs: ddl (required), sql (required). Returns: result

rewrite_queryA

Rewrite a slow query into a cheaper, equivalent one and PROVE the improvement by EXPLAIN-ing both and comparing planner cost. Call after a preflight flags a query expensive/dangerous. Returns the rewritten query, what changed, before/after cost, and index suggestions — ONLY suggesting a btree index when the filter is selective enough to help (an HNSW index for a vector target). Includes equivalence caveats. Pass target= in a multi-DB setup.

Inputs: sql (required), target. Returns: result

suggest_queryA

Grade a query you (the agent) wrote for a user's data request and get told whether to RUN it or REFINE it — the check step of generate->check-> refine. Workflow: (1) describe_schema_tool to learn columns + indexes, (2) write a candidate for the user's intent, (3) call this. Returns next_action: 'accept' (cheap/moderate — run it) or 'refine' (expensive/ dangerous — here are the high-severity flags + a VERIFIED cheaper rewrite; fix and call again). You write the SQL; Anumana owns cost truth. Bound your loop to ~3 rounds. Pass target= in a multi-DB setup.

Inputs: intent (required), candidate_sql (required), target. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation3/5

    The set has a dense cluster around cost-checking a query: preflight_query, suggest_query, and rewrite_query all assess/verify query cost and rewrite behavior, making it non-obvious which to call first (descriptions do disambiguate via the generate->check->refine framing). The preflight_* trio is well-separated by scope (SQL vs vector vs offline DDL), and explain_query_working is distinct as a teaching tool.

    Naming Consistency3/5

    Most names follow a verb_noun pattern (list_targets, list_policies, rewrite_query, suggest_query) and the preflight_* prefix is consistent. However, describe_schema_tool adds a redundant '_tool' suffix and explain_query_working ends in '_working', breaking the pattern in two places.

    Tool Count5/5

    Nine tools is well-scoped for a query cost-analysis/enforcement server, with each tool covering a recognizably distinct surface (targets, policies, three preflight variants, rewrite, explanation, schema, grading). No bloat or thinness.

    Completeness4/5

    The domain (analyze/grade/rewrite queries without executing them) is covered end-to-end: discover targets, inspect schema, learn policies, preflight SQL/vector/offline, rewrite, and explain. Minor gaps exist, e.g. no explicit connectivity/health probe or standalone equivalence-verification tool, but core workflows are complete.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enforces safety and governance for SQL queries executed by AI agents, providing read-only enforcement, cost estimation, and audit trails.
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to format SQL, explain queries in plain English, analyze schemas, build queries from natural language, and generate migrations, all without requiring a database connection.
      5
      43 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to pre-flight estimate query costs, enforce hard budgets, reconcile actual billed spend, and suggest cheaper rewrites across BigQuery, Snowflake, and Databricks.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI coding agents to perform deterministic database architecture audits and performance engineering for PostgreSQL and MySQL, covering migration analysis with schema health scoring, ESR-based composite index recommendations, N+1 query detection, EXPLAIN plan diagnosis, transaction and deadlock analysis, partitioning and archival design, and capacity or configuration tuning. It also generates phased Expand & Contract runbooks that turn blocking DDL into zero-downtime production migrations.
      8
      MIT