MCP Database Manager

AIエージェントが自律的にデータを蓄積・管理できる、セルフドキュメンティング型MCPサーバー

特徴

🤖 AIファースト設計

• 事前知識不要: AIエージェントがMCPに接続するだけで、使い方を完全に理解できる
• セルフドキュメンティング: 全ツールに詳細な日本語説明、使用例、エラーガイド付き
• メタデータ必須: データベース/テーブル/カラムすべてに説明が必須（5文字以上）

🧰 汎用DBオペレーション強化（v2）

• トランザクションAPI: execute_transaction_tool で複数操作をアトミックに実行
• バルク挿入最適化: bulk_insert_optimized_tool で大量データを高速に投入
• Prepared Statement管理: prepare_statement_tool 系列で繰り返しクエリを高速化
• バッチクエリ実行: execute_batch_queries_tool で複数SELECTを一括処理
• DBメタ情報拡張: get_database_info_tool がインデックス・外部キー・PRAGMAを返却

🔍 発見可能性

• 使い方ガイドツール: get_usage_guide_tool で全体像を即座に把握
• 情報階層ツール: DB一覧 → DB詳細 → テーブル詳細と段階的に探索可能
• サンプルデータ表示: テーブル情報取得時に実データ3件を自動表示

🔒 安全性

• トランザクション管理（ロールバック対応）
• ファイルシステム隔離（databases/ディレクトリ内のみ）
• データベース削除時の2段階確認

クイックスタート

1. uvのインストール

まず、uvパッケージマネージャーをインストールします：

curl -LsSf https://astral.sh/uv/install.sh | sh

インストール後、シェルを再起動するか、以下のコマンドでPATHに追加します：

source $HOME/.local/bin/env

2. 依存関係のインストール

# プロジェクトディレクトリに移動
cd /path/to/mcp-agent-external-memory

# 依存関係のインストール
uv sync

3. MCP設定

Claude Desktopの場合

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

{
  "mcpServers": {
    "database-manager": {
      "command": "/Users/your-username/.local/bin/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-agent-external-memory",
        "run",
        "src/server.py"
      ]
    }
  }
}

重要:

• /Users/your-username/.local/bin/uv をuvの実際のパスに置き換えてください（which uvで確認できます）
• /absolute/path/to/mcp-agent-external-memory を実際のプロジェクトパスに置き換えてください

Cursorの場合

プロジェクトルートに.mcp.jsonまたは.cursor/mcp.jsonを作成：

{
  "mcpServers": {
    "database-manager": {
      "command": "/Users/your-username/.local/bin/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-agent-external-memory",
        "run",
        "src/server.py"
      ]
    }
  }
}

注意: Cursorの環境ではuvコマンドがPATHに含まれていない場合があるため、フルパスを指定することを推奨します。

4. 再起動

Claude DesktopまたはCursorを再起動して設定を反映させます。

AIエージェント向けガイド

Step 1: 使い方を理解する

MCPに接続したら、まず get_usage_guide_tool() を呼び出してください。このツール1つで、サーバーの全体像、スキーマ形式、ワークフロー、ベストプラクティスが分かります。

Step 2: 既存DBを確認する

list_databases_tool() でDB一覧を取得できます。各DBの目的、テーブル数、レコード数が表示されます。

Step 3: DB詳細を理解する

気になるDBがあれば、get_database_info_tool(database_name) で詳細を取得。データベースの説明、スキーマ情報、作成日時などが分かります。

Step 4: テーブル構造を把握する

get_table_info_tool(database_name, table_name) でテーブルの詳細を確認。各カラムの説明と実際のサンプルデータ（最大3件）が表示されます。

Step 5: 新規DBを作成する

メタデータ（説明文）を必ず含めて作成してください。スキーマ形式は get_usage_guide_tool() で確認できます。

create_database_tool(
    database_name="book_collection",
    schema={
        "database_description": "個人の蔵書を管理するデータベース",
        "tables": [{
            "table_name": "books",
            "table_description": "所有している書籍の情報を格納するテーブル",
            "columns": [
                {
                    "name": "id",
                    "type": "INTEGER",
                    "description": "書籍を一意に識別するID",
                    "constraints": "PRIMARY KEY AUTOINCREMENT"
                },
                {
                    "name": "title",
                    "type": "TEXT",
                    "description": "書籍のタイトル名",
                    "constraints": "NOT NULL"
                }
            ]
        }]
    }
)

提供ツール（全18種）

ツール名	用途	必須パラメータ
get_usage_guide_tool	使い方ガイドを取得	なし
list_databases_tool	DB一覧を取得	なし
get_database_info_tool	DB詳細情報・インデックス・PRAGMAを取得	database_name
get_table_info_tool	テーブル詳細とサンプルデータを取得	database_name, table_name
create_database_tool	新規DB作成（メタデータ必須）	database_name, schema
create_table_from_csv_tool	CSVから新規テーブル作成＋一括インポート	database_name, table_name, csv_path, table_description, column_descriptions
export_data_tool	テーブル/DB全体をCSV/JSONにエクスポート	database_name, output_path, table_name（オプション）, format（オプション）
insert_data_tool	データ挿入	database_name, table_name, data
query_data_tool	SQL実行（SELECT/UPDATE/DELETE/ALTER等）	database_name, sql_query
execute_transaction_tool	複数操作をアトミックに実行	database_name, operations
bulk_insert_optimized_tool	大量データをバッチ挿入	database_name, table_name, records
prepare_statement_tool	Prepared Statementを作成	database_name, statement_id, sql
execute_prepared_tool	Prepared Statementを実行	database_name, statement_id, params
close_prepared_tool	Prepared Statementをクローズ	database_name, statement_id
execute_batch_queries_tool	複数クエリを一括実行	database_name, queries
store_markdown_to_record_tool	Markdownファイルの内容をレコード・カラムに格納	database_name, table_name, record_identifier, column_name, md_file_path
get_schema_tool	スキーマ取得（互換目的）	database_name, table_name
delete_database_tool	DB削除（2段階確認）	database_name, confirm

メタデータ必須ポリシー

このサーバーでは、すべてのデータベース、テーブル、カラムに5文字以上の説明が必須です。これにより、1週間後や他のAIエージェントでも、DBの目的と構造を即座に理解できます。

必須項目

• ✅ database_description: データベースの目的（5文字以上）
• ✅ table_description: テーブルの役割（5文字以上）
• ✅ column.description: 各カラムの意味（5文字以上）

バリデーション

メタデータが不足している場合、詳細なエラーメッセージで修正方法を案内します。

使用例

シナリオ1: 蔵書管理

ユーザー: 「私の本をデータベースで管理したい」

AIの動作:
1. create_database_tool で book_collection を作成
2. insert_data_tool で書籍データを挿入
3. query_data_tool で「読了」した本を検索
4. 結果をユーザーに報告

シナリオ2: CSVファイルからテーブル作成

ユーザー: 「このCSVファイルをデータベースにインポートして」

AIの動作:
1. CSVファイルのヘッダー行を確認
2. 各カラムの説明文（5文字以上）を準備
3. create_table_from_csv_tool で新規テーブル作成＋一括データ挿入
   - データ型は自動推測（INTEGER, REAL, TEXT）
   - PRIMARY KEYも指定可能
4. get_table_info_tool でインポート結果を確認

シナリオ3: 既存DBの再利用

ユーザー: 「1週間前に作ったDBに追加データを入れて」

AIの動作:
1. list_databases_tool でDB一覧確認
2. get_database_info_tool で目的のDBを特定
3. get_table_info_tool でスキーマ確認
4. insert_data_tool で新データ追加

検証結果

外部AIエージェント（Claude Sonnet 4.5）による検証テスト結果:

• ✅ 事前知識: ゼロ
• ✅ 所要時間: 8分
• ✅ 完了シナリオ: 4/4（全成功）
• ✅ 評価: 5点/5点（全項目満点）
• ✅ 推奨度: 強く推奨

主なフィードバック:

• "get_usage_guide_toolが秀逸。これ一つで全体像を完全に把握できた"
• "メタデータ必須設計により、後から見ても理解できる"
• "サンプルデータ表示が実用的。説明だけでなく実例で理解できる"

詳細: tests/validation/MCP_TEST_REQUEST_COMPLETED.md

新しいスモークテスト

tests/test_server.py を実行すると、トランザクション/バルク挿入/Prepared Statement/バッチクエリなど v2で追加された汎用機能を含む包括的なスモークテストが走ります。

uv run python tests/test_server.py

全テストが成功すると、各機能の実行ログと結果がコンソールに表示されます。

ディレクトリ構成

mcp-agent-external-memory/
├── src/
│   ├── server.py          # MCPサーバー（FastMCP）
│   └── db_operations.py   # DB操作ロジック
├── tests/
│   ├── test_server.py     # 単体テスト
│   └── validation/        # 外部検証テスト結果
│       ├── MCP_TEST_REQUEST.md
│       └── MCP_TEST_REQUEST_COMPLETED.md
├── databases/             # DBファイル保存先（.gitignore）
├── design/
│   └── 設計書.md
├── pyproject.toml
└── README.md

トラブルシューティング

MCPサーバーが起動しない

uvコマンドが見つからない（ENOENTエラー）

Cursorなどの環境では、uvコマンドがPATHに含まれていない場合があります。設定ファイルでuvのフルパスを指定してください：

{
  "mcpServers": {
    "database-manager": {
      "command": "/Users/your-username/.local/bin/uv",
      ...
    }
  }
}

uvのパスを確認する方法：

# uvのインストール場所を確認
which uv
# または
echo $HOME/.local/bin/uv

# uvがインストールされていない場合は再インストール
curl -LsSf https://astral.sh/uv/install.sh | sh

その他の確認事項

# uvが正しくインストールされているか確認
uv --version

# 依存関係を再インストール
uv sync

# 設定ファイルのパスを確認（src/server.py を含める）
# MCPサーバーを直接実行してテスト
uv run src/server.py

スキーマ定義エラー

エラーメッセージに従って修正してください。よくあるエラー:

• メタデータが5文字未満
• database_description が未定義
• columns 配列に description フィールドがない

get_usage_guide_tool() でスキーマ形式の例を確認できます。

データベースが見つからない

# すべてのDBを確認
list_databases_tool()

# 特定のDBの詳細を確認
get_database_info_tool(database_name="your_database")

ライブラリとして使用する

このパッケージはMCPサーバーとしてだけでなく、Pythonライブラリとしても使用できます。 他のMCPサーバーやPythonアプリケーションから直接インポートして使用できます。

インストール

# 開発モードでインストール（推奨）
pip install -e /path/to/mcp-agent-external-memory

# または、パッケージ化してから
cd /path/to/mcp-agent-external-memory
pip install .

基本的な使い方

from database_manager import (
    create_database,
    insert_data,
    query_data,
    get_database_info,
    execute_transaction,
    bulk_insert_optimized,
)

# データベース作成
create_database(
    database_name="my_app",
    schema={
        "database_description": "アプリケーション用データベース",
        "tables": [{
            "table_name": "users",
            "table_description": "ユーザー情報を格納",
            "columns": [{
                "name": "id",
                "type": "INTEGER",
                "description": "ユーザーID",
                "constraints": "PRIMARY KEY AUTOINCREMENT"
            }]
        }]
    }
)

# データ挿入
insert_data(
    database_name="my_app",
    table_name="users",
    data={"name": "Alice", "email": "alice@example.com"}
)

# クエリ実行
result = query_data(
    database_name="my_app",
    sql_query="SELECT * FROM users WHERE name = 'Alice'"
)

# トランザクション実行
execute_transaction(
    database_name="my_app",
    operations=[
        {"type": "insert", "table_name": "users", "data": {...}},
        {"type": "query", "sql": "UPDATE ...", "params": [...]}
    ]
)

データベースディレクトリの設定

環境変数 MCP_DB_DIR でデータベースファイルの保存先を変更できます：

export MCP_DB_DIR=/shared/databases
python your_app.py

デフォルトは databases/ ディレクトリ（パッケージルートからの相対パス）です。

他のMCPサーバーから使用する例

# umw-mcp/server.py など
from database_manager import insert_data

@mcp.tool()
def capture_page_tool(url: str) -> dict:
    # Playwrightでページ取得
    markdown = get_page_as_markdown(url)
    
    # 共通DBに直接保存（LLM経由ではない）
    result = insert_data(
        database_name="umw_survey",
        table_name="page_captures",
        data={
            "url": url,
            "markdown": markdown,
            "captured_at": datetime.now().isoformat()
        }
    )
    return result

公開API一覧

以下の関数が公開されています：

• create_database - データベース作成
• insert_data - データ挿入
• query_data - SQLクエリ実行
• get_table_schema - テーブルスキーマ取得
• get_table_info - テーブル詳細情報取得
• get_database_info - データベース詳細情報取得
• list_all_databases - データベース一覧取得
• delete_database - データベース削除
• create_table_from_csv - CSVからテーブル作成
• export_table_to_csv - テーブルをCSVにエクスポート
• execute_transaction - トランザクション実行
• bulk_insert_optimized - バルク挿入最適化
• prepare_statement - Prepared Statement作成
• execute_prepared - Prepared Statement実行
• close_prepared - Prepared Statementクローズ
• execute_batch_queries - バッチクエリ実行

詳細は各関数のdocstringを参照してください。

技術スタック

• Python: 3.10+
• MCP Framework: FastMCP
• Database: SQLite
• Package Manager: uv

ライセンス

MIT License