atlas-introspect-mcp

ATLAS が自分自身を参照・編集できるようにする MCP サーバー:

HTTP APIを経由する理由

チャット履歴、ワークスペース、プロンプトはすべて1つの DuckDB ファイル（data/chat_history.db）に格納されています。DuckDB はシングルライターであり、ATLAS プロセスはその書き込みロックをプロセス全体の存続期間中保持します。そのため、別のプロセスがファイルを開こうとすると、読み取り専用であっても、ロック競合で失敗します。そこで、このサーバーはループバック HTTP 経由で ATLAS に問い合わせます。これにより、ユーザーごとのスコープもここで再実装するのではなく、ATLAS によって強制されます。

mcp.json と prompts/*.md のみが直接操作されます。ATLAS にはどちらにも API がありません。

別プロセスであることが、ATLAS へのコールバックを安全にします。ATLAS はこのサーバーの stdio 応答を待つ間、自身のイベントループはリクエストを処理するために空いたままです。同じことをプロセス内ツールで行うとデッドロックします。

Related MCP server: Atlas MCP Server

アイデンティティ

すべてのクエリは1人のユーザーにスコープされ、X-User-Email として送信されます。DEBUG_MODE=true の場合、ATLAS はそのヘッダーを尊重します。オフの場合、ヘッダーは認証プロキシが提供したものになるため、同じフラグがどちらの場合でも機能します。デフォルトは test@test.com です。これはデバッグモードで ATLAS がフォールバックするテストユーザーであり、したがってこのホスト上の UI を通じて作成された会話の所有者です。

インストール

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

スタンドアロンチェック（ATLAS 実行中）:

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

ATLAS に登録する

ATLAS の config/mcp.json に追加します（絶対パス — コマンドはシェルの PATH ではなく、サービス管理の PATH で検索されます）。その後、ATLAS を再起動します:

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

ビュー専用ビルドにするには、コマンドに "--read-only" を追加します。すると、すべての変更ツールは書き込みの代わりに拒否します。

ポート: stdio は不要です。--transport http はデフォルトで 8101 です。ポート 8080 は完全に拒否します。k3s を実行しているホストでは、klipper-lb が 8080 を Traefik に DNAT します（127.0.0.1 を含む）。そのため、そこにバインドされたサーバーは何も受信せず、すべてのリクエストはログに何も残らない空の 500 として返されます。

設定

すべてのフラグには環境変数による同等のものがあります。

ツール

会話（読み取り専用） — list_conversations, search_conversations, get_conversation, list_conversation_tags

config/mcp.json — get_mcp_config, upsert_mcp_server, delete_mcp_server, replace_mcp_config

ワークスペース — list_workspaces, create_workspace, update_workspace, delete_workspace

カスタムプロンプト — list_custom_prompts, get_custom_prompt, create_custom_prompt, update_custom_prompt, delete_custom_prompt

ディスク上のプロンプトファイル — list_prompt_files, read_prompt_file, write_prompt_file

ヘルス — atlas_status

注意点

• mcp.json の編集は即時反映されません。 ATLAS は起動時に stdio サーバーを起動します。すべての書き込みツールはその結果にその旨を記載します。適用するには systemctl --user restart atlas または ./redeploy.sh --no-pull を実行してください。

• 自分自身のエントリの編集は機能しますが、再起動後にのみ有効になります。 その時点でエントリが壊れていると、このサーバーは消えてしまい、ATLAS 内から修正できません。バックアップはファイルの隣に mcp.json.bak-<スタンプ> として作成されます。

• upsert_mcp_server はエントリを丸ごと置き換えます、マージはしません。まず読み取り、変更し、全体を送り返してください。ワークスペースの config やプロンプトの content も同様です。

• 会話ツールは設計上読み取り専用です。 ATLAS には削除エンドポイントがありますが、ここでは意図的に公開していません。

• write_prompt_file はインスタンス内のすべてのチャットを変更します。 まずバックアップを作成し、mcp.json と同様に次の再起動時に適用されます。

テスト

.venv/bin/pytest

これらは、一時ディレクトリに対してファイル編集と検証ロジック（アトミック書き込み、バックアップ、トラバーサル拒否、lint 警告、読み取り専用モード）をカバーしています。実行中の ATLAS は不要です。