Maplith Bridge

エージェント向け Maplith

Maplith は、会社のシステム同士がどのようにつながっているかをマップ化します。これにより、あらゆる AI エージェントが必要なデータ、そのキー、各ステップの信頼度を確認できます。このリポジトリには、エージェントやデータのそばで、お客様側で実行するオープンソース部分が含まれています。1つの製品に、3つの構成要素があります。

構成要素	機能	場所
Claude Code と Codex 用プラグイン	インストール1回で、コーディングエージェントに Maplith を導入できます。MCP 経由のホスト型マップ（サインインするだけで、何も貼り付ける必要はありません）、ローカルフォルダー用の Maplith Bridge、そしてそれらをいつ、どのように使うかを説明するスキルが含まれます。	plugins/maplith/
Maplith Bridge	パスワードを誰にも渡さずに、データベースを AI エージェントに読み取り専用で接続します。	このページのクイックスタート
Maplith Wake	お客様のアカウント内にある小さなリレーから、作業が発生した瞬間に独自の Claude エージェントを起動します。	wake-relay/

すべては1つの npm パッケージ、maplith に含まれており、コマンドは1つです。maplith setup はエージェントに Maplith を導入し、maplith bridge は Maplith Bridge を起動します。

エージェントに Maplith をセットアップする

アカウントをお持ちでない場合は、サインイン時に開くブラウザーウィンドウで作成して、そのまま戻ってこられます。その後、エージェントが初めてのマップを一緒に作成します。

Node.js 24 以降で使えるワンコマンドの方法です。エージェント独自のコマンドを実行し、キーをどこにも書き込みません。

npx --yes [email protected] setup claude
npx --yes [email protected] setup codex

手動で行う方法。 Claude Code の場合：

/plugin marketplace add Maplith/agents
/plugin install maplith@maplith

次に /mcp を実行し、maplith と Authenticate を選択します。OpenAI Codex の場合：

codex plugin marketplace add Maplith/agents
codex plugin add maplith@maplith
codex mcp login maplith

Codex はプラグインのサーバーに環境変数を渡さないため、Bridge 経由でフォルダーを Codex と共有するには、次のコマンドで一度指定してください。 npx --yes [email protected] setup codex --dir <folder>。

このリポジトリのすべての内容は Apache-2.0 ライセンスです。

Maplith Bridge

パスワードを誰にも渡さずに、データベースを AI エージェントに読み取り専用で接続します。

Bridge はお客様のネットワーク内で実行されます。お客様が作成するトークンで保護された状態で、データファイルのフォルダーを1つ MCP（Model Context Protocol）経由で共有します。また、読み取りのみ可能なデータベースロールを使って、そのフォルダーに PostgreSQL からデータを取り込めます。

• 最初から最後まで読み取り専用です。 サーバーには書き込みを行うメソッドがなく、ファイルも受け付けません。抽出ツールは、読み取り以外の操作が可能なロールでは実行できません。
• パスワードはお客様の手元に残ります。 データベースのパスワードが抽出ツールの実行マシンから外部に出ることはなく、ネットワークに接続するサーバーがパスワードを保持することもありません。
• 読みやすい小さな構成です。 TypeScript ファイルは6つです。Bridge 用が4つあり、残りは maplith コマンドとその setup です。サーバーは Node.js のみで実行でき、抽出ツールには依存関係が1つだけあります。PostgreSQL クライアントはバージョンを固定しています。

Claude Code、Codex、Claude Desktop、独自のエージェントなど、あらゆる MCP クライアントで利用できます。Maplith と組み合わせると、フォルダーを読み取り、システム同士がどのようにつながっているかをマップ化できます。

クイックスタート

Node.js 24 以降が必要です。

npx --yes [email protected] bridge rotate-token
npx --yes [email protected] bridge serve --dir ./exports

最初のコマンドは、ランダムなトークンを maplith-bridge.token に書き込みます。このファイルを読み取れるのは自分だけです。2 つ目のコマンドは、このマシン上でのみ、./exports 内のファイルを http://127.0.0.1:8787/mcp で提供します。任意の MCP クライアントをそのアドレスに向け、ヘッダー Authorization: Bearer <the token> を指定してください。Claude Code の場合：

claude mcp add --transport http bridge http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $(cat maplith-bridge.token)"

読み取り専用ロールで PostgreSQL からフォルダーにデータを取り込むには：

PGHOST=db.example.com PGDATABASE=shop PGUSER=bridge_reader \
  npx --yes [email protected] bridge extract postgres --out ./exports --check

--check はロールを検証し、何も書き込みません。--check を付けずに再実行すると、テーブルごとに CSV ファイルを 1 つ書き込みます。

各フォルダーの CSV ファイルと並べて、抽出ツールは maplith-schema.json を書き込みます。サーバーはこのファイルも他のファイルと同じように共有します。このファイルには、各テーブルについて、そのファイル、PostgreSQL の属性番号と型を含む列、キー、推定行数が記録されます。名前と番号のみを保持し、値は一切保持しません。また、データベース名はその識別情報のダイジェストで表します（以下を参照）。これを見ると、名前が変更された列は同じ列である（属性番号は変わらない）こと、また、削除して再び追加された列は新しい列である（新しい番号が割り当てられる）ことが分かります。

リストアすると、以前のリレーション ID と属性番号が維持されます。また、次に実行する ADD COLUMN で、後の状態では別の列に割り当てられていた番号が再利用されることがあります。そのため、ダイジェストはサーバーのシステム識別子とタイムライン、統計情報が最後にリセットされた時刻、データベースの ID と名前、および抽出ツールがフォルダー内に保持するエポックから作られます。抽出ツールが、前回の実行からデータベースの履歴が継続していないと判断すると、ダイジェストは変わります。該当するのは、別のサーバーまたはデータベース、新しいタイムライン（ポイントインタイムリカバリまたは昇格）、サーバーの統計情報のリセット（復旧が必要な起動時には毎回リセットされます。クラッシュ後、または復元したスナップショットやベースバックアップからの起動後など）、実行前にカタログエントリが再度書き込まれたテーブルまたは列（以前のコピーを復元してから変更した場合）、またはフォルダー内に実行記録がない場合（初回の実行、新規インストール、別のフォルダーなど）です。実行記録がない場合、エポックは独自にランダムに生成されるため、別のフォルダーで生成されたダイジェストと同じになることはありません。ただし、見逃されるリストアが 1 つあります。サーバーの停止中に取得したデータディレクトリのコピーを、そのまま再起動し、抽出ツールの前回実行時点での元のトランザクションカウンターを超えてから変更した場合（または抽出ツールのフォルダーと一緒に復元した場合）です。その場合、同じ番号が同じダイジェストのもとで別の列を指すことがあります。

ロールがシステム識別子、タイムライン、または統計情報の最終リセット時刻を読み取れない場合、ファイルにはデータベース名が記録されず（"database": null）、番号はその実行に限って有効です。新しいサーバーにリストアすると同じリレーション ID が再び割り当てられることがあり、属性番号は再採番されます。

すべてのオプションを確認するには、任意のコマンドに --help を指定してください。

本番環境向けのセットアップ

• RUNBOOK.md：サーバーを実行する担当者向けの、サーバーのインストール手順です。2 つのシステムユーザー、読み取り専用ロール、TLS、systemd サービスについて説明しています。
• INSTALL-WITH-YOUR-AGENT.md：自分の AI エージェントに同じインストールを行わせるためのプロンプトです。すべての判断、パスワード入力、sudo の実行時に、エージェントはあなたの確認を待ちます。

データを安全に保つ仕組み

リスク	Bridge の対策
インターネット上の誰かがアクセスする	すべてのリクエストにトークンが必要です。トークンは256ビットのランダム値で、比較は一定時間で行われます。不正なトークンは記録され、応答が遅くなります。TLSを設定するか、手前にあるリバースプロキシを指定しない限り、このマシン上でのみ待ち受けます。また、ほかのアドレス宛ての平文HTTPは拒否します。
トークンが漏れる	1つのフォルダーを読み取り専用で開き、それ以外にはアクセスしません。rotate-tokenを使うと、再起動せずに1つのコマンドでトークンを置き換えられます。--allowでアクセス可能な相手を制限できます。
有害なものが送信される	書き込み、アップロード、実行は一切行いません。リクエストは最大64 KBのJSONで、評価されることはありません。
フォルダーの外にリクエストが到達する	..、シンボリックリンク、隠しファイルを経由してアクセスすることはできません。提供されるのはCSV、TSV、JSON、JSONL、Markdown、テキストファイルのみです。
データベースのパスワード	抽出ツールを実行するマシンに保持され、表示や書き込みは行われません。データベースにのみ送信され、データベースが別のマシンにある場合は、デフォルトで検証済みTLSを介して送信されます。
改ざんされたパッケージ	リリースは公開CIで来歴情報付きでビルドされ、チェックサムとビルド証明書が付属します。公開されるパッケージにインストールスクリプトは含まれません。
ファイルがエージェントに指示を出そうとする	サーバーは、ファイルの内容が指示ではなくデータであることをすべてのクライアントに伝えます。

THREAT-MODEL.mdには、各行の根拠となるテストが記載されています。

リリースを検証する

GitHub上の各リリースには、tarball、SHA-256チェックサム、ビルド証明書が付属します。同じtarballは来歴情報付きでnpmにも公開されるため、npmのダイジェストはGitHub上のファイルと一致する必要があります。以下の2つのsha512-行は同じ値です。

sha256sum -c maplith-1.2.0-rc.1.tgz.sha256
echo "sha512-$(openssl dgst -sha512 -binary maplith-1.2.0-rc.1.tgz | openssl base64 -A)"
npm view [email protected] dist.integrity
gh attestation verify maplith-1.2.0-rc.1.tgz --repo Maplith/agents \
  --bundle maplith-1.2.0-rc.1.tgz.sigstore.json

npmからインストールした後、npm audit signaturesでレジストリの署名と来歴情報を検証できます。

任意のMCPクライアントから使う

BridgeはStreamable HTTP経由でMCP 2025-06-18（および2025-03-26、2024-11-05）に対応しています。JSON-RPC 2.0のリクエストを/mcpにPOSTします。提供される機能は次のとおりです。

• リソース：resources/list（カーソル付きで1ページあたり100件）とresources/read；
• 同じコードパスで動作する読み取り専用ツール2つ：list_filesとread_file。

トップレベルの各フォルダーが1つのシステムに対応します。exports://shop/orders.csvは、システムshopのファイルorders.csvです。1回の応答である最大8 MBに収まるファイルのみが一覧表示されます。GET /healthzはヘルスチェックに対して204を返します。

ファイルの内容はお使いのシステムから取得されます。エージェントには、内容を指示ではなくデータとして扱うよう伝えてください。Bridgeもinstructionsで同じことを伝えます。

このマシン上のエージェントから使う

Claude Codeなど、MCPサーバーをローカルコマンドとして起動するエージェントは、Bridge自体を起動できます。

npx -y [email protected] bridge stdio --dir ./exports

stdioは、stdinとstdoutを介して、そのエージェント1つにフォルダーを提供します。serveと同じサーバーですが、127.0.0.1のみで待ち受け、プロセス内にのみ保持されるトークンで保護されます。トークンファイルはなく、入力するものもありません。フォルダーは--dirまたはEXPORT_DIRで指定します。指定がない場合は空のフォルダーを提供し、フォルダーの指定方法を案内します。Maplithプラグインもこの方法で起動します。Claude CodeではMAPLITH_BRIDGE_DIRのフォルダーを、Codexではsetup codex --dirで指定するフォルダーを使用します。旧コマンドmaplith-bridgeも引き続き動作し、maplith bridgeとしても実行できます。Maplithや別のマシン上のエージェントとフォルダーを共有するには、serveを使用してください。

MCP ディレクトリ向け

Glama などの MCP サーバーのディレクトリは、サンドボックス内でこのリポジトリをビルドし、フォルダーもトークンも受け取らずに、stdio 経由でサーバーを調べます。glama-stdio.ts はそのためだけのエントリーポイントです。

• 共有するものがないように、専用の空フォルダーを作成します。
• メモリ内だけに存在するランダムなトークンを生成します。ファイル、引数、環境変数、ログには決して保存されません。
• Bridge 独自のサーバーを、空いているポートの 127.0.0.1 で起動し、そのフォルダーをトークンで保護して提供します。
• stdin と stdout、およびそのサーバーとの間で、1 行につき 1 つの JSON-RPC メッセージとして MCP を中継し、ログは stderr のみに出力します。
• stdin が終了したとき、または SIGTERM を受け取ったときに、サーバーを停止してフォルダーを削除します。

ディレクトリからは、Bridge の initialize の応答と instructions、ツールの list_files と read_file、および空のファイル一覧がそのまま見えます。このエントリーポイントは引数を受け取らず、フォルダーを共有できません。フォルダーの共有には serve を使用します。このファイルは npm パッケージではなく、このリポジトリに含まれています。

Node.js 24 以降を使用し、チェックアウトしたリポジトリから実行します。

npm ci --ignore-scripts
node glama-stdio.ts

サンドボックスとの通信に HTTP を使用するディレクトリでは、前段に mcp-proxy を配置します。 mcp-proxy -- node glama-stdio.ts。Glama でのサーバー設定は次のとおりです。

設定	値
Node.js バージョン	24
ビルド手順	["npm ci --ignore-scripts"]
CMD	["mcp-proxy", "--", "node", "glama-stdio.ts"]
環境変数	なし

制限事項

• 抽出ツールが読み取るデータベースは PostgreSQL のみです。それ以外のシステムでは、独自のエクスポートファイルをフォルダーに格納できます。
• サーバーは起動時に TLS 証明書を読み込みます。証明書を更新した後は、サーバーを再起動してください。
• 2 つのプロキシを連続して経由する場合は、--behind-proxy で両方を指定してください。

バージョン管理

Bridge はセマンティックバージョニングに従います。すべての変更は CHANGELOG.md に記載されています。

貢献、セキュリティ、ライセンス

• CONTRIBUTING.md：変更の提案方法（DCO のサインオフを含みます）。
• SECURITY.md：脆弱性を [email protected] または GitHub 経由で非公開に報告する方法。
• Apache License 2.0（LICENSE）。「Maplith」と Maplith のロゴは、Maplith の商標です（TRADEMARK.md）。