anumana

Anumana

クエリを実行する前に、そのコストがわかります。 AI が作成するすべてのクエリに、推論品質の先見性を。

Anumana は、AI コーディングエージェントが今まさに作成した高コストなクエリを、実行されたり PR に到達したりする前に検知する MCP サーバーです。Claude、Cursor、Windsurf、Codex、Kiro、または MCP 互換エージェントに組み込まれ、EXPLAIN（EXPLAIN ANALYZE は使用しません）で実際のスキーマを読み取り、クエリの動作や、問題を引き起こす可能性があるかどうかを平易な言葉で伝えます。

対象は、AI エージェントが実際に生成するクエリです。現在はテキストから SQL への変換に加え、**RAG／ベクトル検索（pgvector）**にも対応しています。類似検索を作成するエージェントは、すべての埋め込みを対象にブルートフォーススキャンを開始したことに気づかないためです。Anumana は、エージェントに欠けているフィードバックループです。

これは、新たな NL→SQL ツールではなく、データベース健全性ダッシュボードでもありません。役割はただひとつ、AI が作成したデータベースコードによって、本番環境が気づかないうちに劣化するのを防ぐことです。

---

機能

ツール	わかること
preflight_query	「この SQL クエリは高コストですか？」 — リスクレベル（低コスト／中程度／高コスト／危険）、スキャン行数と返却行数、スキャン方式、オーバーヘッドのフラグを、実行せずに確認できます。
preflight_vector_search	「この RAG 類似検索は高コストですか？」 — 通常の SQL チェックでは見逃すベクトル検索の落とし穴を検出します。HNSW／IVFFlat インデックスのないブルートフォーススキャン、大きすぎる top_k、上限のない検索、メタデータフィルターによる ANN の再現率低下などが対象です。
rewrite_query	「もっと低コストにしてください。」 — 検証済みの等価な書き換えと、書き換え前後のプランナーコストを提示します。さらに、選択性を条件としたインデックス候補も提案します（フィルターがテーブルの大部分に一致する場合、その列へのインデックス作成は提案しません）。engine="pgvector" の場合は HNSW インデックスを提案します。
explain_query_working	「これはどのように実行されますか？」 — 2 つのレイヤーを説明します。論理的な取得順序（FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT）と、スキーマに基づく実際の物理プランを、段階を追って示します。
preflight_schema_only	「まだデータベースの認証情報を渡していません。」 — 接続せずに、貼り付けた CREATE TABLE DDL に対して静的解析を行います。オフラインで動作する、ゼロトラストの入口です。

エンジン（7 つのパラダイムにわたる 12 種類）： Postgres と SQLite は実環境でテスト済みです。MySQL、pgvector、MongoDB、DynamoDB、FalkorDB、Cassandra、Redshift、BigQuery、Snowflake、ClickHouse は、オフラインで検証済み・未テストのアダプターとして提供され、順次ひとつずつ実環境対応に昇格します。対応状況の一覧とコストシグナルはSUPPORTED_ENGINES.mdをご覧ください。アダプターのインターフェースはDESIGN.mdに記載されています。

正直さを貫く唯一のルール

Postgres のプランナーコストは単位のない値であり、ミリ秒ではありません（ドキュメント）。Anumana は~3.2sのような数値をでっち上げません。スキャン行数、スキャン方式、リスクレベル、オーバーヘッドのフラグ、書き換えによるコスト差分を、根拠を示せる形で報告します。推測による情報は一切ありません。すべての推定値には精度レベル（実環境ではUPPER_BOUND、スキーマのみの場合はHEURISTIC）が付与されます。

---

インストール

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

次に、エージェントから利用できるように設定します。インストールするのはユーザーです。エージェントは接続時に MCP のtools/listハンドシェイクを介してツールを自動的に検出します。公開先となるストアはありません。

Claude Desktop／Cursor／Windsurf／Kiro — mcpServers 設定ブロック

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

読み取り専用の Postgres ロールを使用してください。Anumana はEXPLAINのみを実行しますが、多層防御のため読み取り専用にします。スキーマのみのモード（DDL を入力し、データベースには接続しない）で実行する場合は、ANUMANA_DSNを省略してください。

---

データベースなしで試す（30 秒）

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

実際の Postgres でテストする

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

実データでコスト差分と選択性ゲートを検証する、psqlベースのハーネスについてはsrc/live_test.pyをご覧ください。

---

意図的に含めていないもの

run_query（SQL は実行しません）、NL→SQL（エージェントがすでに行います）、データベース健全性レポート、ドル建ての課金額はありません。対象を絞ることが戦略です。

ライセンス

MIT — LICENSEをご覧ください。

コミュニティと連絡先

貢献を歓迎します。CONTRIBUTING.mdと行動規範をご覧ください。データベースエンジンの追加は、最も効果の高い貢献です。アダプターの仕様はシンプルです（SUPPORTED_ENGINES.md）。

• バグ／アイデア：GitHub のイシューを作成してください。
• セキュリティ：SECURITY.mdをご覧ください。非公開で報告してください。
• **メンテナー：**[email protected]