Anumana

io.github.sinhaKAN-rav0.2.1更新于 Oct 5, 2026

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

已验证STDIO仅桌面Developer ToolsAI & MLDatabases

概览

AI 生成的概览

Anumana 让助手在不执行查询的情况下预检 SQL 与向量搜索查询，估算成本、风险等级和扫描策略。

功能
Anumana 提供在查询运行前进行分析的工具：preflight_query 给出风险等级、扫描行数与返回行数、扫描策略和开销标记；preflight_vector_search 捕捉向量搜索陷阱，例如缺少 HNSW 或 IVFFlat 索引、top_k 过大；rewrite_query 提出经验证的等价改写，附改写前后规划器成本，并按选择性给出索引建议；explain_query_working 展示逻辑收集顺序与实际物理计划；preflight_schema_only 针对粘贴的 CREATE TABLE DDL 做静态分析，无需连接。它通过 EXPLAIN（绝不使用 EXPLAIN ANALYZE）读取真实 schema，覆盖 7 类范式的 12 种引擎，其中 Postgres 与 SQLite 经过实测，其余为离线验证的适配器。
适用场景
当 AI 编码助手编写 SQL 或 RAG 相似度搜索，而你希望在查询运行或进入拉取请求之前做成本与风险检查时使用。适合希望尽早发现暴力向量扫描、无界搜索或高开销计划的团队。它不是自然语言转 SQL 工具，也不是数据库健康仪表盘。
运行要求
通过 stdio 在本地运行，可从 PyPI 安装 anumana-mcp（pip install anumana-mcp）或从源码安装，需要 Python 运行时。数据库访问通过只读连接字符串 ANUMANA_DSN 配置，多数据库场景使用 ANUMANA_TARGETS；两者均可选，省略时进入仅 schema 模式。ANUMANA_POLICIES 可选，用于设置阻止、警告或允许规则。
安装前请注意
ANUMANA_DSN 与 ANUMANA_TARGETS 是包含数据库连接字符串的机密，请使用只读角色；服务器只发出 EXPLAIN，但只读权限是纵深防御。ANUMANA_POLICIES 默认开放，只有配置后强制规则才生效。规划器成本是无单位的，不是毫秒，且每个估算都带有准确度等级，因此仅 schema 模式的结果应按启发式看待。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Anumana，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 2694d0e

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.2.1最新Oct 5, 2026