Archive MCP Server

Enterprise Data Archival & Records Management System のレコードと保持ロジックを、stdio を介してあらゆる MCP クライアント — Claude Code、Claude Desktop、Cursor、または独自のクライアント — に公開する MCP サーバーです。

React ダッシュボードをクリックして 「Finance で何をアーカイブできるか？」 に答える代わりに、モデルに質問すると、モデルがこれらのツールを呼び出します。

ツール

Related MCP server: EndpointRead-MCP

リソース

要件

Python 3.10+ と MCP SDK 2.x が必要です。v2 SDK は FastMCP を MCPServer に改名し、mcp.server.mcpserver に移動しました。このコードは v2 を対象としています。データアクセスは SQLAlchemy 2.x で、PostgreSQL には psycopg2 を使用します。

セットアップ

python -m venv .venv
source .venv/bin/activate          # macOS/Linux
.venv\Scripts\activate             # Windows

python -m pip install -r requirements.txt
python seed_db.py                  # builds the local demo database
python server.py --selftest        # sanity check, no MCP client needed

次に、実際の MCP セッションで確認します：

python verify_mcp.py

データベースの選択

サーバーは DATABASE_URL を読み取ります（環境変数、または .env ファイルから — .env.example を参照）：

archive.db には合成レコードが入っているため、サーバー — および --selftest — は、認証情報なしでこのリポジトリをクローンした人なら誰でも実行できます。これは別のコードベースではありません。seed_db.py は、本番データベースが使用する同じ 5 テーブル構成のスキーマ（active_records、archived_records、retention_policy、audit_logs、documents）を構築するため、server.py 内のすべてのクエリはどちらのデータベースに対しても変更なしで動作します。

実際の DATABASE_URL をコミットしないでください。 .env は gitignore されており、.env.example がコミット対象のテンプレートです。

Claude Code への接続

プロジェクトディレクトリから：

claude mcp add --scope project archive-system -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py
claude mcp list

--scope project は、コミット可能な .mcp.json をプロジェクトルートに書き込むため、リポジトリをクローンした人なら誰でもサーバーを利用できます。claude を起動し、プロンプトが表示されたらプロジェクトサーバーを承認し、/mcp を確認してください — archive-system が Connected と 6 つのツールを表示するはずです。その後、次のように質問します：

どの IT 部門のレコードがアーカイブ期限を過ぎていますか？

起動に失敗した場合は、claude --debug=mcp を実行し、~/.claude/debug/ のログを確認してください。

Claude Desktop への接続

claude_desktop_config.json に次を追加します：

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

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

{
  "mcpServers": {
    "archive-system": {
      "command": "D:\\Python\\project\\archive-mcp\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Python\\project\\archive-mcp\\server.py"]
    }
  }
}

command は、素の python ではなく venv の Python を指すようにしてください — ホストはシェルの PATH やアクティベートした仮想環境を継承しないためです。Windows では両方のパスに二重のバックスラッシュが必要です。

トレイアイコンから再起動します — ウィンドウの閉じるボタンではなく Quit です — そうしないと、アプリは古い設定のまま動き続けます。

Windows の Microsoft Store（MSIX）ビルドに関する注意：その設定は %APPDATA% ではなく、パッケージ独自のディレクトリ %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\ にあります。ローカル stdio サーバーを通常どおり起動します。logs\mcp.log でそれを確認しようとしないでください — そのファイルは、すべてが正常に動作している間も空のまま触られずにいることがあります。代わりにプロセスを確認してください。サーバーは Claude Desktop の子プロセスとして実行されます：

Get-CimInstance Win32_Process -Filter "Name like '%python%'" |
  Where-Object { $_.CommandLine -like "*archive-mcp*" }

設計ノート

• stdio トランスポート — クライアントが同一マシン上でサーバーをサブプロセスとして起動するためです。サーバーがリモートで動き、複数のクライアントにサービスを提供するのであれば、HTTP トランスポートが理に適います。

• ストレージの継ぎ目は 1 か所。 _connect() は SQLAlchemy の Engine を返し、データベースが何であるかを知っている唯一の場所です。クエリは名前付きバインドパラメータ（:department）を使用します。これはダイアレクト非依存なので、SQLite と PostgreSQL は 2 つではなく 1 つのクエリセットを共有します。

• pool_pre_ping=True — サーバーレス PostgreSQL（Neon など）はアイドル中のコンピュートをサスペンドし、MCP サーバーは質問と質問の間アイドル状態になるためです。これがないと、静かな期間の後の最初の質問が、古いプール接続で失敗します。

• 適格性は SQL ではなく Python で計算します。 PostgreSQL の INTERVAL 演算には SQLite に相当するものがなく、比較を 1 か所に保つことで 2 つのバックエンドの一貫性が保たれます。有効行が数千件程度であれば、このコストを最適化して除去する価値はありません。

• 経過期間は joining_date から測定します。 created_at は一括ロードのタイムスタンプで全行で同一のため、そこから保持期間を計算しても、適格なものは決して見つかりません。joining_date は文書日付の代わりとなる従業員レベルの日付です — スキーマには文書日付がなく、これは上流で埋める価値のある実際のギャップです。

• アーカイブ状態はフラグではなくテーブルです。 レコードは active_records か archived_records のいずれかに存在し、ID は移動をまたいで安定しているため、get_record は両方を確認します。status カラムは雇用ステータスであり、無関係です。

• ツールは読み取り専用として注釈付けされています。 各ツールは ToolAnnotations(read_only_hint=True, destructive_hint=False) を持つため、クライアントは実行前に安全な呼び出しと状態を変更する呼び出しを区別できます。

• ツールは実際にも読み取り専用です。 アーカイブは破壊的であり、ポリシーによって統制されています。archival_candidates は、アーカイブできるものを意図的に報告し、判断は既存のスケジュールジョブに委ねます。破壊的なツールをモデルに公開するのは、まず確認経路が必要な選択です。

• ドクストリングが API です。 モデルはドクストリングと型ヒントからツールを選ぶため、有効な部署と文書タイプはそこに列挙されています。古い enum はないよりも悪いです。モデルが Legal のようなもっともらしい値を渡し、空の結果を受け取り、アーカイブするものは何もないと報告するからです。

• 「適格」の定義は 1 つで、双方向に使用します。 _verdict は、レコードが保持期間に対してどれだけ経過したかを評価し、_eligible_on はそれを逆にして、レコードがその期間を超える日付を返します。retention_forecast は、その日付でバケットに分類します。この 2 つは正確に一致する必要があります。そうでないと、同じ日にレコードがフォーキャストでは 予定 と表示され、archival_candidates では 期限超過 と表示される可能性があります。逆を自明な方法で書くと（joining + timedelta(days=years * 365.25)）、date + timedelta は整数日のみを保持し、.75 を黙って切り捨てるため、これが壊れます。

• 出力は整形されたテキストであり、生の JSON ダンプではありません。 モデルが再フォーマットなしでそれをユーザーに引用して返せるようにするためです。