Skip to main content
Glama
deenesjakoruzh
SurajKGoyal

amnesic

by SurajKGoyal
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

amnesic — レジストリで最も皮肉な名前のMCPサーバー

PyPI version Python License: MIT MCP Registry Glama score

あなたのデータベースの組織的記憶を、MCPサーバーとして。名前は皮肉です——すべてを覚えています。

「レジストリで最も皮肉な名前のMCPサーバー。決して健忘症ではありません——あなたのデータベースを覚えているので、あなたのAIが覚える必要はありません。」

ほとんどのデータベースMCPサーバーはクエリ実行器です。接続し、イントロスペクトし、SQLを実行し、忘れます。amnesicは意味的記憶です——スキーマが意味すること（status = 3が何か、どの列が実際には外部キーか、そのレガシーテーブルが何のためのものか）を蓄積し、将来のすべてのセッションに自動的に渡します。データカタログを、プラットフォーム、取り込みパイプライン、請求書なしで考えてください。amnesicの位置づけ ↓

対応クライアント Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf — あらゆるMCP互換クライアント。

入手先 公式MCPレジストリ · Claude Codeプラグインマーケットプレイス

👋 amnesicを使っていますか？ 採用者スレッドで挨拶してください — ダウンロード数では実際に何が使われているかわかりません。それが次に作るものを直接形作ります。

🔒 設計上読み取り専用。 amnesicはINSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、MERGE、GRANT、REVOKE — およびWITH CTE内に紛れ込んだ書き込み文を拒否します。防御は2層です。静的SQL解析が接続前に文を拒否し、さらにすべてのクエリは即座にロールバックされるトランザクション内で実行されます。本番環境に向けても安全です。詳細 ↓

問題

AIとのセッションは毎回冷たい状態で始まります。最初の数分は、どのテーブルが存在するか、status列の値3が何を意味するか、どのFKがordersをusersに接続するかを再説明することに費やします。そしてセッションが終わると、明日また同じことを繰り返します。

amnesicがこれを解決します。 AIに永続的なSQLite知識ストアを提供します——データベースごとに1つ——セッションをまたいで存続します。ステータスenumを一度注釈すれば、将来のすべてのセッションがそのラベルを自動的に見ます。FK関係を一度発見すれば、将来のすべてのJOINクエリがそのグラフを使用します。

知識は移植可能で、データベースへのアクセスがなくなっても存続します。 プロジェクトを離れるとき、amnesic exportはあなたが教えたすべてを次の開発者に渡します——「ああ、あの列は実は…」という何年分の知識が、あなたとともに去ってしまうのを防ぎます。

Related MCP server: engram-mcp

amnesicの位置づけ

データベースMCPエコシステムは2つの陣営に分かれますが、amnesicは意図的にどちらにも属しません。

クエリ実行器 — DBHub、Postgres MCP Pro、GoogleのMCP Toolbox、およびベンダーサーバー（Supabase、Neon）。ライブでイントロスペクトし、SQLを実行し、一部はパフォーマンスに深く踏み込みます——Postgres MCP Proは本格的なインデックスチューニングとPgHeroスタイルのヘルスチェックを行います。これらは非常に優れています。しかしステートレスでもあります。すべてのセッションがスキーマをゼロから再学習し、返すものは列が意味することを教えてくれません。データベース自体も知らないからです。

エンタープライズカタログ — DataHub、Atlan、Cube、AtScale。これらは確かに意味的コンテキストを保持します。用語集、列の説明、所有権、系統。しかし、プラットフォームへのコミットメントでもあります。メタデータの取り込み、実行するサービス、通常は有料層。企業規模では価値がありますが、誰もカタログにオンボードしないレガシーMSSQLデータベースの6つのステータスコードの意味を覚えておく必要がある一人の開発者には、不釣り合いに大掛かりです。

amnesicは第三のものです：クエリ実行器のセットアップコストでカタログ級の意味的記憶を提供します。pipx install、1つのTOMLファイル、データベースごとのローカルSQLiteファイル。プラットフォームも、取り込みも、実行するサーバーもありません。

正直な比較

amnesic

クエリ実行器

エンタープライズカタログ

意味的コンテキスト（値が意味すること）

✅ 永続的、あなたのもの

❌ なし

✅ プラットフォーム管理

セッションをまたいで存続

✅

❌

✅

移植可能 / DBアクセスを超えて存続

✅ export/import

❌

⚠️ プラットフォーム依存

セットアップコスト

1コマンド

1コマンド

取り込みパイプライン

ライブスキーマの鮮度

⚠️ キャッシュ、手動更新

✅ 常にライブ

⚠️ 取り込み遅延

実行計画 / インデックスチューニング

❌

✅ (Postgres MCP Pro)

❌

系統 / 所有権 / ガバナンス

❌

❌

✅

FK制約のないレガシースキーマで動作

✅ 自分で注釈可能

❌ イントロスペクトするものがない

⚠️ 取り込みが必要

amnesicの代わりにクエリ実行器を使うべき場合：実行計画、インデックス推奨、データベースのヘルス診断が必要な場合——それはamnesicの仕事ではなく、追加すると既存ツールの劣化版になってしまいます。

amnesicを併用する場合：両者は補完します。両方を実行しても問題ありません。amnesicが意味を保持し、クエリ実行器が仕組みを保持します。

上記の⚠️の行は既知のギャップで、オープンなissueがあります——ロードマップ ↓を参照してください。

クイックスタート（90秒）

pipx install amnesic            # install the core
amnesic init                    # interactive wizard

⚡ 資格情報なしで試す。 代わりにamnesic init --demoを実行してください——自己完結型のSQLiteサンプルDB（eコマーススキーマ：顧客/製品/注文、FKとenum列付き）を追加し、1分以内ですべてのツールを試せます。実際のデータベースにamnesicを向ける前に、まず試すのに最適です。

ウィザードは接続するデータベースの種類を尋ね、ドライバがまだインストールされていない場合に実行すべき1つのコマンドを教えてくれます——事前に余分なものを推測する必要はありません。

ウィザード：

  • データベースの種類、ホスト、資格情報を尋ねます

  • 何も保存する前に接続をテストします

  • パスワードを~/.config/amnesic/.env（chmod 600）に安全に保存します

  • 接続ブロックを~/.config/amnesic/connections.tomlに書き込みます

次にamnesicをAIクライアントに追加して再起動します。

pipxをインストール（一度だけ）：

brew install pipx                                  # macOS
sudo apt install pipx                              # Linux (Debian/Ubuntu)
python -m pip install --user pipx                  # Windows / generic

またはuvを使用（シングルバイナリの代替——高速、Python不要）：

brew install uv                                            # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh            # Linux / macOS
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows

uv tool install amnesic

または素のpip（アクティブなPython環境にインストール）：

pip install amnesic

どれを選んでも、amnesic initは接続するデータベースを尋ね、そのドライバをインストールするための1つの追加コマンドを表示します——事前に余分なものを決める必要はありません。

インストール後、amnesic --helpは任意のターミナルで動作します。

amnesicがデータを保存する場所

ファイル

macOS / Linux

Windows

設定

~/.config/amnesic/connections.toml

%APPDATA%\amnesic\connections.toml

シークレット

~/.config/amnesic/.env (chmod 600)

%APPDATA%\amnesic\.env (ユーザープロファイルACL)

知識

~/.config/amnesic/knowledge_<name>.db

%APPDATA%\amnesic\knowledge_<name>.db

$AMNESIC_HOME（またはLinuxでは$XDG_CONFIG_HOME）を設定して場所を上書きできます。

後で接続を追加する

amnesic add          # add another connection to existing config
amnesic test         # verify all connections
amnesic test orders.prod  # verify one connection

パスワードの設定とローテーション

amnesic initとamnesic addはパスワードを自動的に保存します——通常のセットアップフローでは、このセクションを考える必要はありません。

後で保存済みパスワードを変更する必要がある場合にset-secretを使用します——ITがローテーションした、セットアップ中に誤入力した、または設定を手動編集している場合です。

$ amnesic set-secret ORDERS_PROD_PASSWORD
Value: ****            ← hidden input (your typing is invisible)
Confirm: ****
✓ Set ORDERS_PROD_PASSWORD in ~/.config/amnesic/.env

変数名は何ですか？ それはconnections.tomlがその接続のパスワードに参照する環境変数です。ウィザードはこれらを<接続名_大文字_アンダースコア>_PASSWORDとして自動生成します：

接続名

生成される環境変数

orders.prod

ORDERS_PROD_PASSWORD

analytics

ANALYTICS_PASSWORD

drive.staging

DRIVE_STAGING_PASSWORD

設定が使用する正確な名前を確認するには、~/.config/amnesic/connections.tomlを確認してください——${...}内のものはすべてset-secretに渡す変数です。

内部動作：~/.config/amnesic/.envの行を書き込む（または置き換える）、ファイル権限をchmod 600に設定（あなたのユーザーのみが読み取り可能）、他のすべてのエントリを保持します。

接続と知識の管理

知識は接続ごとにローカルSQLiteファイルに蓄積されます。以下のコマンドで、マシン間で移動したりクリーンアップしたりできます：

# Hand off everything you've taught amnesic about a database (annotations +
# relationships, not the re-derivable schema cache) as portable JSON:
amnesic export orders.prod -o orders-knowledge.json
amnesic export orders.prod            # or print to stdout to pipe/redirect

# Load that knowledge into another connection (e.g. promote staging → prod,
# or onboard a teammate). Unconditional upsert — existing entries are overwritten:
amnesic import orders.prod orders-knowledge.json

# Wipe stored knowledge for a connection but keep the config entry:
amnesic clear orders.staging

# Drop a connection from connections.toml entirely (knowledge file kept
# unless you pass --delete-knowledge):
amnesic remove old.connection
amnesic remove old.connection --delete-knowledge

export/import/clear/removeはローカルファイルのみを操作します——データベースには接続しないため、接続の資格情報が設定されていなくても動作します。removeはconnections.tomlを外科的な文字列編集で変更し、他のすべてのブロックの書式とコメントをバイト単位でそのまま保持します。

AIクライアントに追加

正しいドライバのextras付きでamnesicがインストールされると（クイックスタートを参照）、amnesicコマンドがPATHに含まれます。すべてのMCPクライアントで同じスニペットを使用します：

Claude Code

ワンラインインストール（推奨——JSON編集不要）。Claude Code内で：

/plugin marketplace add https://github.com/SurajKGoyal/amnesic-marketplace
/plugin install amnesic@amnesic

これでamnesicがMCPサーバーとして自動的に配線されます。出典：SurajKGoyal/amnesic-marketplace。

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Claude Desktop

プラットフォームのClaude Desktop設定に追加：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Cursor

ワンクリックインストール — 下のボタンをクリックするとCursorが配線します：

プロジェクトの.cursor/mcp.json（またはグローバルに~/.cursor/mcp.json）に追加：

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

グローバルインストールなし（一時的）

システムにamnesicをインストールしたくない場合は、uvxまたはpipxを使用してMCPクライアントの起動時に毎回取得します。ドライバのextrasを明示的に渡す必要があることに注意：

// uvx — requires `uv` installed (see Install section for per-OS instructions)
{
  "mcpServers": {
    "amnesic": {
      "command": "uvx",
      "args": ["--from", "amnesic[mssql]", "amnesic"]
    }
  }
}

// pipx — usually pre-installed via Homebrew or system package manager
{
  "mcpServers": {
    "amnesic": {
      "command": "pipx",
      "args": ["run", "--spec", "amnesic[mssql]", "amnesic"]
    }
  }
}

複数のドライバの場合は、ブラケット内でカンマ区切りにします——例：amnesic[postgres,mssql]、またはすべての場合はamnesic[all]。

VS Code（MCP拡張機能付き）

.vscode/mcp.jsonに追加：

{
  "servers": {
    "amnesic": {
      "type": "stdio",
      "command": "amnesic"
    }
  }
}

更新

amnesicは頻繁にリリースされます。インストールに使用したのと同じツールでアップグレードします：

インストール方法

アップグレードコマンド

pipx

pipx upgrade amnesic

uv tool

uv tool upgrade amnesic

pip

pip install --upgrade amnesic

uvx（一時的、MCP 設定内）

uvx はビルドをキャッシュします — 最新版を取得するには uv cache clean amnesic を実行してください

その後、MCP クライアント（Claude Code、Cursor など）を再起動して、amnesic サーバーを再起動し、新しいツールを認識させてください。

アップグレードは安全です — アノテーションは失われません。 ナレッジファイルは初回ロード時に自動的に新しいスキーマへ移行されます。amnesic は列を追加するだけで、データを削除することはありません。

インストール済みバージョンの確認: amnesic --version。最新リリース: PyPI · Releases。

ツール

ツール

説明

db_list_connections()

設定済みの全接続を一覧表示（シークレットは非表示）

db_list_tables(connection)

説明と列数を含む既知の全テーブル

db_search(query, connection, target, limit)

テーブル/列の説明とエイリアスに対する BM25 検索

db_get_schema(table, connection)

保存済みアノテーションとマージされた列スキーマ

db_query(sql, connection)

読み取り専用の SELECT クエリを実行

db_annotate(table, connection, ...)

テーブル/列のセマンティックアノテーションを永続化

db_deprecate(table, connection, column?, reason?, undo?)

古いアノテーションをソフトリタイア — フラグ付き（警告あり）で保持、元に戻し可能

db_detect_drift(connection)

アノテーションとライブスキーマを監査 — 孤立アノテーションと未ドキュメント化テーブルを検出

db_forget(table, connection, column?, cascade?)

アノテーションをハード削除（カスケードはオプトイン）— 永久的

db_sync_knowledge(from, to)

接続間でアノテーションをコピー（例: staging → prod）

db_discover_relationships(connection)

ライブ DB からすべての FK リレーションシップを検出

db_get_relationships(table, connection)

JOIN 計画のための FK グラフをナビゲート

ナレッジベースの検索

大規模なスキーマでは、db_list_tables は非現実的です — 500 行以上を Claude のコンテキストにダンプすることになります。代わりに db_search を使用して、キーワードで関連するテーブル/列を検索してください:

"What table tracks customer payments?"
  → db_search("payments")
    Top results:
      - dbo.payments  (table) "Customer payment records..."
      - dbo.orders.payment_method  (column) "Mode of payment..."

db_search は SQLite FTS5 と BM25 ランキングを使用 — 高速、ローカル、埋め込みや外部サービスは不要です。検索構文は以下をサポート:

構文

効果

payment

単語に一致（ステミングあり — "payments"、"paying" にも一致）

"payment method"

完全一致フレーズ

pay*

前方一致 — "payment"、"payable" など

payment AND status

両方の用語が必要

payment OR refund

いずれかの用語

結果は、説明とハイライトされたスニペット付きのランク付けされたテーブル/列の行を返します。

ナレッジレイヤー

中核となる差別化要因。すべてのアノテーションは、再起動、モデル更新、新しいセッションを超えて存続します。

セッション 1 — 何かを発見する

You: What does status=3 mean in the orders table?
AI: Let me check. [runs db_query: SELECT DISTINCT status FROM dbo.orders]
    I see values 1, 2, 3, 4. Let me look at some examples...
    Based on the data, 3 appears to be "cancelled".

You: Save that. And status=1 is "pending", 2 is "confirmed", 4 is "delivered".
AI: [calls db_annotate]
    db_annotate(
      table="dbo.orders",
      column="status",
      column_description="Order lifecycle status",
      enum_values={"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}
    )
    Saved. Future sessions will see these labels automatically.

セッション 2 — ナレッジはすでにそこにある

You: How many cancelled orders are there this month?
AI: [calls db_get_schema("dbo.orders")]
    Schema response includes:
      column: "status"
      description: "Order lifecycle status"
      enum_values: {"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}

    [writes correct SQL immediately]
    SELECT COUNT(*) FROM dbo.orders WHERE status = 3 AND ...

再発見は不要。無駄なターンも不要。アノテーションは永続化されました。

リレーションシップグラフ

スキーマの JOIN 構造を一度理解すれば、それを永遠に再利用できます。

AI: [db_discover_relationships(connection="orders.prod")]
    Discovered 47 foreign key relationships.

AI: [db_get_relationships(table="orders", depth=2)]
    neighbors:
      orders → users (via user_id → id)
      orders → order_items (via id ← order_id)
    paths:
      orders -> users
      orders -> order_items
      order_items -> products

これで AI は推測することなく、スキーマ全体で正確に JOIN する方法を正確に把握できます。

環境間の同期

staging でアノテーションを構築し、prod に昇格させます:

db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")

{synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]} を返します。

ターゲットのスキーマキャッシュに存在しないテーブルは、明確な理由とともにスキップされます。ターゲットスキーマに存在しない列は警告されますが、同期の残りをブロックしません。

上級: TOML の手動編集

設定ファイルを自分で管理したい場合は、空のテンプレートを生成します:

amnesic init --template

これにより、コメント付きの例を含む ~/.config/amnesic/connections.toml が書き込まれ、終了します — ウィザードはありません。ファイルを直接編集してください:

# ~/.config/amnesic/connections.toml

# Nested style: [connections.product.env]
[connections.orders.prod]
driver = "mssql"
server = "localhost"
port = 11433
database = "OrdersDB"
user = "${ORDERS_USER}"
password = "${ORDERS_PROD_PASSWORD}"
tunnel_script = "~/.scripts/mssql-tunnel.sh"     # macOS / Linux (bash)
# tunnel_script = "C:/scripts/mssql-tunnel.ps1"  # Windows (PowerShell)

[connections.orders.staging]
driver = "mssql"
server = "localhost"
port = 11434
database = "OrdersDB_Staging"
user = "${ORDERS_USER}"
password = "${ORDERS_STAGING_PASSWORD}"

# Flat style: [connections.name]
[connections.analytics]
driver = "postgres"
server = "analytics.company.com"
port = 5432
database = "warehouse"
user = "${ANALYTICS_DB_USER}"
password = "${ANALYTICS_DB_PASSWORD}"

# SQLite — no credentials needed
[connections.local]
driver = "sqlite"
database = "/absolute/path/to/local.db"       # macOS / Linux
# database = "C:/path/to/local.db"            # Windows (use forward slashes)

認証情報には ${ENV_VAR} を使用してください — パスワードをハードコードしないでください。

シークレットは ~/.config/amnesic/.env から自動的に読み込まれます（形式: KEY=VALUE、1 行に 1 つ、# はコメント）。TOML で参照されている各 ${VAR_NAME} について、amnesic set-secret VAR_NAME（非表示入力、chmod 600）で一致する .env エントリを設定するか、.env を自分で記述してください。

正規の接続名はドット記法を使用します: orders.prod、orders.staging、analytics、local。

サポートされているデータベース

データベース

Python ドライバー

インストール方法

PostgreSQL

psycopg2-binary

Postgres を選択したときのウィザードの案内、または amnesic[postgres] エクストラ

MySQL / MariaDB

pymysql

MySQL を選択したときのウィザードの案内、または amnesic[mysql] エクストラ

Microsoft SQL Server

pymssql

MSSQL を選択したときのウィザードの案内、または amnesic[mssql] エクストラ

SQLite

標準ライブラリ sqlite3

常に利用可能 — 追加不要

安全性と読み取り専用の強制

amnesic は本番データベースに向けても安全に使用できるように設計されています。

AI がデータを損傷できない理由

すべてのクエリは、データベースに到達する前に2 つの独立したレイヤーを通過します:

  1. 静的解析（amnesic/readonly.py 内）— SQL はトークン化され、以下が含まれる場合は拒否されます: INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、EXECUTE、MERGE、BULK、GRANT、REVOKE、DENY。 これには CTE 内に紛れ込んだ書き込みステートメントも含まれます（WITH x AS (SELECT ...) UPDATE ... は検出され拒否されます）。

  2. トランザクションのロールバック — 静的チェックをすり抜けたとしても、クエリは BEGIN TRANSACTION ... ROLLBACK 内で実行されるため、コミットされることはありません。二重の安全策です。

データベースに到達するのは SELECT と WITH ... SELECT のみです。解析前にコメントは削除されるため、/* DELETE FROM users */ で攻撃を隠すことはできません。

その他の安全対策

  • レスポンスに認証情報を含めない: db_list_connections は出力からパスワードとユーザー名を削除します。AI はどの接続が存在するかは確認できますが、それらへの認証方法は決して確認できません。

  • 認証情報は環境変数のみ: 設定読み込み時に ${ENV_VAR} を展開 — パスワードがディスク上の connections.toml に触れることはありません。

  • 安全な .env ストレージ: macOS/Linux では chmod 0o600（所有者のみ読み書き可能）; Windows では .env は %APPDATA% に配置され、Windows ACL によりユーザープロファイルに制限されます。

  • 識別子の検証: テーブル/スキーマ/データベース名は、SQL への文字列補間の前に [A-Za-z0-9_]+ に対してチェックされます。

  • テスト済み: tests/test_readonly.py の 40 以上のユニットテストが、すべての書き込みキーワード、コメント削除のエッジケース、CTE を使った書き込み試行、セミコロン区切りの複数ステートメント、識別子インジェクションの試行をカバーしています。pytest tests/test_readonly.py で自分のマシンで検証できます。

これは私のデータにとって安全ですか？

amnesic はローカルのみ、プロトコルのみです。新しい外部トラストバウンダリを導入しません — トラストバウンダリは MCP クライアントがデータを送信する場所であり、amnesic 自体ではありません。 AI クライアントを選択することで、行に適用されるポリシーが決まります。

your DB → amnesic (local) → MCP client → your AI deployment
                                          ↑ trust boundary lives here

インディーでもエンタープライズでも、問うべき正直な質問は次のとおりです:

このデータベースのデータを AI クライアントに任せてもよいか？

もし「はい」なら — そしてほとんどのセットアップでは答えは「はい」です — 問題ありません。これには以下が含まれます:

  • 自分のプロジェクト、開発 DB、テストデータで Claude Pro / Cursor / Copilot を使用する個人開発者

  • 個人用 SQLite やセルフホスト Postgres をクエリするサイドプロジェクト

  • 公開スキーマで作業するオープンソースメンテナー

  • 明示的な分離を備えたエンタープライズ AI を使用するチーム: AWS Bedrock（テナント + IAM）、Azure OpenAI（リージョン固定、自社サブスクリプション）、Anthropic Enterprise（ゼロデータ保持、トレーニングオプトアウト）、Vertex AI（自社 GCP プロジェクト）、セルフホスト（Ollama、vLLM、オンプレミスの Claude/GPT — データがネットワーク外に出ることはありません）

  • ゼロ保持保証とユースケースをカバーする DPA を備えた有料 AI プランを利用しているすべての人

より慎重な検討が必要な場合

  • DB に他の人に属するデータ（ユーザー、顧客、患者）が含まれており、AI プロバイダーの規約がその処理をカバーしていることを確認していない場合

  • コンシューマー向け AI（無料 / 個人向け Pro）を利用しており、かつ規制対象データ — PHI（HIPAA 対象エンティティ）、カード会員データ（PCI-DSS）、GDPR / インドの DPDP 法に基づく制限付き PII — を扱っている場合

  • 雇用主が本番 DB での外部 AI ツールの使用を制限する明示的なポリシーを持っている場合

  • 行を特定のリージョンから出せないデータレジデンシー規則の下にある場合

データ最小化は組み込まれている

後付けではなく設計の特性: アノテーションレイヤーにより、AI はほとんどのスキーマ質問にローカルの SQLite ナレッジファイルから回答します — db_query は実行されず、行データがどこかに送信されることはありません。

  • "status=3 はどういう意味？" → 保存済みアノテーションから解決

  • "orders は users とどう JOIN する？" → FK グラフから解決

  • "created_at 列を持つテーブルはどれ？" → スキーマキャッシュから解決

純粋に構造的な探索の場合、6 つのツールはデータに触れません: db_list_tables、db_get_schema、db_search、db_annotate、db_discover_relationships、db_get_relationships。これらはメタデータのみを返します。

これは、AI が列挙型について混乱するたびに SELECT DISTINCT status FROM orders を実行しなければならない「裸の」SQL MCP よりも、測定可能なほどデータ移動が少ないです。amnesic はローカルのアノテーションから一度で回答します。

免責事項: amnesic は MIT ライセンスの下で現状有姿で提供されます（保証なし、責任なし — LICENSE を参照）。このセクションは法的またはコンプライアンス上のアドバイスではありません。amnesic の使用、および接続する AI クライアントは、お客様の責任です。規制対象データを扱う場合は、本番環境に向ける前にセキュリティ / コンプライアンスチームに相談してください。

ロードマップ

これまでにリリース済み: ナレッジレイヤー（v0.1）、BM25 検索（v0.1.5）、ライフサイクル管理 — 非推奨化 / ドリフト検出 / 忘却（v0.2）、ポータブルナレッジのエクスポート/インポート（v0.2.2）。

次の予定（v0.3 — "Earn the memory"）: 誰も入力しなくても蓄積されるナレッジ — 列挙型の自動検出、制約のないレガシースキーマのためのソフト FK 推論、JOIN パターンの学習。さらに基本的な作業: すべてのレスポンスのトークン予算、スキーマ取得でのインデックスと主キー、キャッシュの鮮度フラグ、より小さなツールサーフェス。

ROADMAP.md を参照して、全体像と順序の根拠を確認してください。

🙌 コントリビューション歓迎

v0.3 の各項目は、設計がすでに考え抜かれた GitHub イシューとして登録されています — 問題、提案された形、触るべきファイル、テスト方法が含まれています。いくつかは good first issue タグが付いています。

1つ選んでPRを開いてください — 事前に尋ねる必要はありません。ただし、同じものを2人が作らないように、イシューにコメントしてください。

リストにないアイデアがありますか? イシューを開いてください。 パッチよりもユースケースの方が重要です — 手戻りを防げます。

使用状況の追跡

pypistats.org/packages/amnesic

ライセンス

MIT — LICENSE を参照してください。

MCP レジストリ

このサーバーは公式 MCP レジストリに登録されています。

mcp-name: io.github.SurajKGoyal/amnesic

Available Tools

12 tools
db_annotateA
Persist semantic annotations for a table or column — survives across sessions.

This is the core of amnesic's persistent memory. Every annotation saved here
is automatically merged into future db_get_schema() responses, so the AI
never has to rediscover what a status code means or what a table is for.

Call this after discovering: what an enum value means, what a column represents,
how a table relates to another, or what a table is used for.

Args:
    table:              Table name, optionally schema-qualified to match your
                        DB — e.g. "users", "public.users" (Postgres),
                        "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:         Connection name. Defaults to first defined.
    table_description:  Human-readable description of the table's purpose.
    table_aliases:      Alternative names the table is known by.
    column:             Column to annotate (required for column-level args below).
    column_description: What this column represents in the business domain.
    enum_values:        Dict mapping stored values to labels {"1": "active", "2": "inactive"}.
    foreign_key:        FK reference as "other_table.column_name".
    example_values:     Representative sample values from this column.

Returns:
    {table, connection, updated: {table_knowledge?, column_knowledge?}}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
table_descriptionNo
table_aliasesNo
columnNo
column_descriptionNo
enum_valuesNo
foreign_keyNo
example_valuesNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It states annotations survive sessions, are merged into future db_get_schema responses, and calls it the core of persistent memory. This effectively communicates the mutating and persistent nature. It doesn't discuss permissions or reversibility, but given the positive intent (annotating for better future queries), the transparency is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a brief summary, contextual motivation, usage guidance, parameter list, and return type. Every sentence adds value, and the length is appropriate for the tool's complexity. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 9 parameters and no annotations or output schema, the description covers the tool's purpose, when to use it, parameter semantics, and return format. It also explains how it integrates with db_get_schema, providing sufficient context for an AI agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage (no descriptions), so the description must compensate. The Args section provides clear semantic explanations for each parameter, including schema qualification for table, relationship between column and column-level fields, and the dict format for enum_values. This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool persists semantic annotations for tables or columns, surviving across sessions. It distinguishes from siblings by positioning itself as the persistent memory mechanism that feeds into db_get_schema, a unique role not covered by other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises calling this tool after discovering semantic knowledge (enum meanings, column purposes, relationships). While it doesn't list when to avoid it or name alternatives, the context and sibling list imply when to use versus when to use other tools like db_get_schema or db_query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_deprecateA
Soft-retire a table or column annotation — flag it stale without deleting it.

Use when a table/column still exists but should no longer be relied on. The
deprecation flag is surfaced in db_get_schema so the AI is warned off it on
future calls. Reversible via undo=True. To remove an annotation entirely
(e.g. the column was dropped from the DB), use db_forget instead.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column to deprecate. Omit to deprecate the whole table.
    reason:     Why it's deprecated (e.g. "replaced by status_v2").
    undo:       Clear the deprecation flag instead of setting it.

Returns:
    {table, connection, column, target, deprecated, reason}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
reasonNo
undoNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description explains the deprecation flag is surfaced in db_get_schema and that operation is reversible. Lacks details on permissions or side effects, but sufficient for a soft-retire tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with summary, usage guidelines, and argument list. Slightly wordy but each sentence adds value. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description covers all inputs, explains return format, and mentions interaction with db_get_schema. Distinguishes from sibling db_forget.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description provides full argument list with detailed explanations, defaults, and usage nuances (e.g., connection defaults to first defined, column omitted means whole table).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool soft-retires a table or column annotation, distinguishing it from db_forget which removes entirely. Specific verb+resource combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (table/column still exists, should not be relied on) and when not (use db_forget instead). Also mentions reversibility via undo=True.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_detect_driftA
Audit saved annotations against the live database schema (read-only).

Surfaces drift after the schema evolves:
  - orphaned annotations — a table or column you annotated that no longer
    exists in the DB. Remove with db_forget, or db_deprecate if pending.
  - undocumented tables — live tables with no annotation yet (coverage gaps).

Changes nothing — purely a report. Run after schema changes, or periodically.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, orphaned_tables, orphaned_columns, undocumented_tables,
     undocumented_truncated, summary}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states the tool is read-only ('Changes nothing — purely a report.') and details what it surfaces (orphaned annotations, undocumented tables). It also outlines the return structure (connection, orphaned_tables, etc.), providing full transparency without relying on annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it opens with a clear verb-resource statement, uses bullet points for key outputs, and includes a separate Args/Returns section. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one optional parameter and no output schema, the description fully covers the tool's function, when to use it, what it detects, and the format of its return. No gaps remain for the intended use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only has one parameter (connection) with default null. The description adds meaning by stating 'Defaults to first defined,' which goes beyond the schema's default value. Given the parameter's simplicity, the description provides sufficient context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Audit saved annotations against the live database schema (read-only).' It specifies the verb (audit) and the resource (annotations vs live schema), and distinguishes itself from sibling tools like db_forget and db_deprecate by emphasizing it is a read-only report that detects drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Run after schema changes, or periodically.' It also advises on follow-up actions ('Remove with db_forget, or db_deprecate if pending.'), making the usage context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_discover_relationshipsA
Discover all foreign key relationships in the database and save them to the graph.

Runs driver-specific FK introspection queries against the live database and
persists results to the local KnowledgeStore. Run once per database; re-run
after schema changes. After discovery, use db_get_relationships to navigate
the graph when planning complex JOIN queries.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, discovered: count, relationships: [{from_table, from_column, to_table, to_column}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: runs driver-specific FK introspection queries, persists to KnowledgeStore, and implies potential impacts (live database query). Could mention performance implications or permissions, but still transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a short summary, usage guidelines, and listed args/returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Completely covers the tool's lifecycle, return format, and relationship to sibling tools. No gaps given the simple parameter set and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an Args section explaining the single parameter 'connection', its meaning, and default behavior ('Defaults to first defined'), adding value beyond the schema which only shows default null.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool discovers all foreign key relationships and saves them to the graph. It uses specific verbs (discover, save) and resources (foreign key relationships, database, graph), and distinguishes from sibling tool db_get_relationships.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('Run once per database; re-run after schema changes') and when not, by directing to use db_get_relationships for navigation after discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_forgetA
Permanently delete a table or column annotation. Safe by default — NOT reversible.

Use to remove a wrong annotation, or to clean up after a table/column was
dropped from the DB (pairs with db_detect_drift). Unlike db_deprecate, this
hard-deletes. Cascade is opt-in so you can't nuke a table by accident:
  - db_forget(table)               -> ONLY the table's own annotation
  - db_forget(table, column="x")   -> ONLY that column's annotation
  - db_forget(table, cascade=True) -> the table + all its column annotations
                                      + all relationships touching it

Only the local knowledge store is changed — never the live database.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column annotation to delete. Omit to target the table.
    cascade:    When targeting a table, also delete its columns +
                relationships. Ignored when column is given.

Returns:
    {table, connection, column, removed_table, removed_columns, removed_relationships}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
cascadeNo

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses behavior. It states 'Safe by default — NOT reversible,' explains cascade behavior, and clarifies that only the local knowledge store is changed, never the live database.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and examples. Every sentence adds value, and critical information is front-loaded immediately after the first line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return object structure. It covers all necessary context: irreversibility, local-only modification, cascade behavior, and relation to siblings. Complete for a destructive knowledge store tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description provides detailed semantics for all 4 parameters: table examples, connection default, column omit behavior, cascade ignored when column given. This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Permanently delete a table or column annotation.' It uses specific verbs and resources, and explicitly distinguishes from siblings like db_deprecate (soft-delete) and pairs with db_detect_drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use to remove a wrong annotation, or to clean up after a table/column was dropped from the DB.' Provides when-not guidance by contrasting with db_deprecate, and explains cascade opt-in to prevent accidents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_relationshipsA
Get the foreign key relationship graph for a table up to the given traversal depth.

Depth 1 returns direct neighbors (tables one JOIN away). Depth 2 returns
neighbors-of-neighbors. Returns both a flat neighbor list and formatted join
path strings to help plan multi-table queries. Requires db_discover_relationships
to have been run first.

Args:
    table:      Table name (e.g. "Orders").
    connection: Connection name. Defaults to first defined.
    depth:      BFS traversal depth (default 1, recommended max 3).

Returns:
    {table, connection, neighbors: [...], paths: ["TableA -> TableB -> TableC", ...]}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
depthNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the output format (neighbor list and join paths) and the prerequisite step. As no annotations are provided, the description carries full burden; it lacks explicit mention of side effects or idempotency but is sufficient for understanding behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for Args and Returns. It is concise without unnecessary words, front-loading the primary purpose and then detailing parameters and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is comprehensive: it explains the output structure, prerequisite, and each parameter fully. An agent can correctly invoke this tool based solely on the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all three parameters, their purposes, defaults, and even a recommended maximum depth for depth. This provides complete semantic understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: retrieving the foreign key relationship graph for a table up to a given depth. It distinguishes itself from sibling tools by explicitly requiring db_discover_relationships to have been run first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it explains depth levels and that the prerequisite tool must be run first. However, it does not explicitly state when not to use this tool or mention alternatives beyond the prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_schemaA
Get column schema for a table, merged with any saved semantic annotations.

Checks the local cache first; fetches from the database on cache miss or
when force_refresh=True. Saves the result to cache for future calls.
Merges column descriptions, enum value mappings, and FK references from
previous db_annotate() calls into the response.

Args:
    table:         Table name, optionally schema-qualified. Use whatever your
                   DB uses — e.g. "users", "public.users" (Postgres),
                   "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:    Connection name. Defaults to first defined.
    force_refresh: Bypass cache and fetch fresh schema from the database.

Returns:
    {table, connection, columns (with annotations merged in), table_description, cached}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
force_refreshNo

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description fully discloses caching behavior, force refresh mechanism, and annotation merging, providing complete behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the purpose, and every subsequent sentence adds necessary detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking output schema, the description covers all essential aspects: purpose, caching, param details, and return structure, making it complete for a 3-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description thoroughly explains each parameter: table with DB-specific examples, connection with default, and force_refresh with functionality, adding significant value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves column schema merged with semantic annotations, distinguishing it from sibling tools like db_annotate (which adds annotations) and db_list_tables (which lists tables).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use (to get annotated schema) and parameter usage, but lacks explicit guidance on when not to use or alternatives to sibling tools, which would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_connectionsA
List all configured database connections without exposing passwords or usernames.

Use this first to see what databases are available before calling other tools.
Returns connection names, drivers, databases, and server addresses.

Returns:
    {connections: [{name, driver, database, server}]}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that passwords and usernames are not exposed, which is a key behavioral trait. However, does not explicitly state read-only nature or any side effects, though implied for a list operation. No annotations to contradict or supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences plus a returns block. Front-loaded with main purpose. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fully explains what the tool does and what it returns (list of connections with name, driver, database, server). No missing info given the simplicity of the tool and absence of parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. Description does not need to add parameter info. Schema coverage is 100% by default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states listing all configured database connections without exposing sensitive info. Differentiates from siblings like db_list_tables by specifying the resource (connections). Uses specific verb 'list' and describes return fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use this tool first before other tools to see available databases. Provides a clear usage context and sequential guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_tablesA
List all known tables for a connection, with descriptions and column counts.

Tables appear once they have been fetched via db_get_schema or annotated via
db_annotate. Descriptions come from the knowledge store — richer than raw
INFORMATION_SCHEMA.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, database, tables: [{table_fqn, description, aliases, column_count}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It discloses that descriptions come from the knowledge store (richer than raw schema) and that tables are only shown if known. No destructive behavior implied. Return format is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear purpose, behavioral notes, Args, and Returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: purpose, prerequisites, return format, and parameter behavior. Complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single optional parameter 'connection' is documented with default behavior ('Defaults to first defined'), adding useful meaning beyond the schema type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists all known tables for a connection, including descriptions and column counts. It distinguishes itself from siblings like db_get_schema (which fetches schema) and db_annotate (which annotates) by noting that tables appear only after those actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context by explaining that tables appear only after being fetched or annotated, guiding the user on prerequisites. However, it does not explicitly state when to use or not use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_queryA
Execute a read-only SELECT query and return rows as a list of dicts.

All queries run inside an immediately-rolled-back transaction — write
statements are blocked both statically and at the transaction level.
Call db_get_schema first if you are unfamiliar with the table structure.

Args:
    sql:        SELECT query to execute. No INSERT/UPDATE/DELETE allowed.
    connection: Connection name (e.g. "orders.prod"). Defaults to first defined.
    max_rows:   Maximum rows to return (default 500). Set lower for large tables.

Returns:
    {rows, row_count, connection, database, truncated}
ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes
connectionNo
max_rowsNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that queries run in an immediately-rolled-back transaction and that write statements are blocked both statically and at the transaction level. It also outlines the return structure (rows, row_count, connection, database, truncated). Since no annotations are provided, the description carries the full burden and does so well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a single sentence stating the core purpose, followed by a brief note on transaction behavior and a recommendation to use a sibling tool, then a bullet-style summary of parameters and return value. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, no output schema), the description covers the main behavioral aspects (transaction, write blocking), parameter semantics, and return format. It could optionally mention error handling or performance implications, but overall it is sufficiently complete for an AI agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description provides comprehensive meaning for all three parameters: sql (SELECT-only), connection (defaults to first defined), and max_rows (default 500, lower for large tables). This goes far beyond the bare schema, which only supplies names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a read-only SELECT query and returns rows as a list of dicts. It specifies that write statements are blocked, making the purpose unambiguous. Although not explicitly compared to siblings, the verb-resource combination ('Execute a read-only SELECT query') is specific and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to call db_get_schema first if unfamiliar with the table structure, providing a clear alternative. It also implicitly limits usage to read-only queries (SELECT only) and mentions max_rows for large tables. However, it does not explicitly exclude other query types or describe when not to use the tool beyond the SELECT constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_sync_knowledgeA
Copy annotations from one connection's knowledge store to another.

Typical use: after confirming that staging and prod share the same schema,
sync all the semantic knowledge you've built up in staging to prod.
Only syncs tables and columns that exist in the target schema cache —
tables missing from target are reported in 'skipped', columns in 'warnings'.

Args:
    from_connection: Source connection (e.g. "orders.staging").
    to_connection:   Target connection (e.g. "orders.prod").
    tables:          Optional list of specific table FQNs to sync. Defaults to all.

Returns:
    {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
from_connectionYes
to_connectionYes
tablesNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully bears the transparency burden. It discloses that only tables/columns existing in target are synced, with skipped and warnings reported. It also describes the return structure in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a typical use case, behavior explanation, and clear Args/Returns sections. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no output schema, and no annotations, the description is highly complete. It covers the sync process, edge cases (missing items), and return format, leaving no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning by explaining 'from_connection' and 'to_connection' as source/target with example values ('orders.staging', 'orders.prod'), and 'tables' as an optional list of FQNs defaulting to all. This provides clarity beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool copies annotations between knowledge stores. It uses a specific verb 'sync' and resource 'annotations from knowledge store', distinguishing it from sibling tools like db_annotate or db_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a typical use case: syncing from staging to prod after confirming schema match. It also explains behavior for missing tables/columns. However, it does not explicitly exclude other scenarios or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv0.2.2
    • First observeddb_annotate
    • First observeddb_deprecate
    • First observeddb_detect_drift
    • First observeddb_discover_relationships
    • First observeddb_forget
    • First observeddb_get_relationships
    • First observeddb_get_schema
    • First observeddb_list_connections
    • First observeddb_list_tables
    • First observeddb_query
    • First observeddb_search
    • First observeddb_sync_knowledge
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose. There is no overlap: annotation management (annotate, deprecate, forget), schema retrieval (get_schema, list_tables), querying (query), searching (search), relationship discovery (discover_relationships, get_relationships), drift detection (detect_drift), and knowledge sync (sync_knowledge) are all separate concerns.

Naming Consistency5/5

All tools follow the consistent pattern `db_<verb>_<noun>` using snake_case. The verbs are descriptive and indicate the action (e.g., annotate, query, list_tables). No mixing of conventions or vague names.

Tool Count5/5

With 12 tools, the server is well-scoped for a database knowledge management system. Each tool serves a necessary function in the lifecycle of schema understanding, annotation, querying, and maintenance. Not overloaded nor sparse.

Completeness4/5

The tool set covers the core workflow: connection listing, table discovery, schema retrieval, querying, annotation CRUD (annotate, deprecate, forget), relationship discovery, drift detection, and knowledge sync. Missing a direct tool to view all annotations in isolation, but schema retrieval and search provide access.

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SurajKGoyal/amnesic'

If you have feedback or need assistance with the MCP directory API, please join our Discord server