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