DevTwin MCP

AIコーディングエージェントに、ローカル開発環境のライブで構造化された理解を与えます。

DevTwin は Model Context Protocol (MCP) サーバーで、AI コーディングエージェントの中心的な問いに対して答えを返します: この開発者の環境はなぜ違うのか、壊れているのか、あるいは不健全なのか?

プロジェクトのテクノロジーを検出し、インストール済みランタイムのバージョンをプロジェクトが実際に要求するものと照合し、依存関係とロックファイルの状態を検査し、必要なローカルサービス (Postgres、Redis、...) を見つけてそれらが実行中かどうかを確認し、ポートと Git の状態をチェックし、それらすべてを構造化されたエビデンスベースの診断に変換します -- 環境をクラウドバックエンドに送信することも、シークレット値をモデルに公開することもありません。

目次

• DevTwin が存在する理由

• FAQ: Claude CLI にはすでにシェルがあるのに、なぜ MCP が必要なのか?

• 利点

• トークンコスト

• 正直なトレードオフ

• DevTwin あり vs. なし: 実例

• これで可能になる質問の例

• 言語別の例

• アーキテクチャ

• 対応エコシステム

• インストール

• MCP クライアント設定

• 別のプロジェクトでの使用

• ツールリファレンス

• セキュリティモデル

• プライバシーモデル

• ローカルファーストアーキテクチャ

• 開発

• コントリビューション

• ロードマップ

• ライセンス

DevTwin が存在する理由

• AI コーディングエージェントはコードをよく読めますが、コードが実際に実行される環境に対しては盲目です。

• 「npm test が自分のマシンで失敗するのはなぜ?」という問題は、通常コードとは無関係です -- Node のバージョン不一致、実行されていないサービス、またはインストールされていない依存関係が原因です。

• DevTwin は、シニアエンジニアが手作業で収集するであろう同じシグナル -- node --version、git status、lsof -i :5432、docker ps -- を、推測ではなく構造化されたツール呼び出しとしてエージェントに提供します。

FAQ: Claude CLI にはすでにシェルがあるのに、なぜ MCP が必要なのか?

これは通常、開発者が最初に抱く質問であり、もっともな質問です。すでに Bash ツールを持つ Claude Code のようなクライアントでは、node --version、docker ps、lsof -i :5432 などを直接実行するよう依頼するだけでよく、MCP サーバーは不要です。DevTwin が埋めるギャップは「そもそもできるかどうか」ではなく、次の点です:

Claude CLI に特化した正直な回答: すでに Bash があるため、DevTwin の利点は「これまで持っていなかった機能」よりも小さく -- 安全性の保証と一貫した構造化出力であり、まったく新しいアクセスではありません。それが無料ではない理由でもあります -- 接続に実際にかかるコストと、それが価値を持つタイミングについては トークンコスト を参照してください。

採用前に検討する価値のある質問がさらにいくつかあります:

「これは手順が増えただけの doctor スクリプト (make doctor、bin/setup) ではないのか?」 概念的にはその通りです -- 成熟したリポジトリの多くはすでに手書きで 1 つ持っています。DevTwin の違いは、ほとんどのリポジトリにはそれがないこと、エコシステムごとに良いものを書くのは実際の作業であること、その出力は人間が読むプレーンテキストではなくエージェントが推論できる構造化 JSON であること、そして同じ 10 個のツールが、プロジェクトごとに独自の慣習と盲点を持つ特注スクリプトではなく、すべてのリポジトリで同一に機能することです。

「Claude / Claude Code でしか動かないのか?」 いいえ。DevTwin は標準の Model Context Protocol を話します -- あらゆる MCP 互換クライアント (Claude Desktop、Cursor、Windsurf など) が同じ方法で接続できます。Claude 固有のものは何もありません。

「依存しても安全か -- 積極的にメンテナンスされているか?」 Alpha ステータス であり、新しいプロジェクトです -- 依存するワークフローで信頼する前に、コードを読んでください (短いです)。他の新しい開発ツールの依存関係と同じように。

「間違ったことを提案したり、悪い推奨事項を自動的に実行したりする可能性はあるか?」 ここにあるツールは recommendations 文字列を実行しません -- それらはエージェント (またはあなた) が読んで判断するための単なるテキストです。dev_check だけが何かを実行する唯一のツールであり、それも固定許可リストに対して自身が認識したコマンドのみです -- セキュリティモデル を参照してください。

「ホームに電話したり、テレメトリをどこかに送信したりするのか?」 いいえ。独自のネットワーク呼び出しはゼロです -- ローカルファーストアーキテクチャ を参照してください。

「MCP サーバーに自分のマシンで何らかのコマンドを実行してほしくない。」 10 個のツールのうち 9 個は純粋に読み取り専用です (ファイル読み取り、バージョンチェック)。dev_check だけが何かを実行し、それも DevTwin 自身がプロジェクトファイルから認識し、許可リストに対してチェックし、shell=False とタイムアウト付きで実行するコマンドのみです -- それが正確に何を許可し、何を許可しないかは セキュリティモデル を参照してください。

利点

• 誤診断の減少。 DevTwin がないと、障害をデバッグするエージェントはコードを読んで推測するしかなく、実際には Node のバージョン不一致や停止したデータベースが原因である問題に対して、コード修正を提案することがよくあります。DevTwin は推測ではなく真実を提供します。

• 多数の呼び出しではなく 1 回の呼び出し。 単一の dev_health 呼び出しで、約 10 個の基盤となるチェック (ランタイムバージョン、依存関係の状態、サービス、ポート、Git) を 1 つの構造化されたスコア付き結果にまとめます -- エージェントが毎回 12 回の個別シェルラウンドトリップを行い、生の CLI 出力を解析する代わりに。

• 毎回同じチェック。 エコシステムごとの正確なチェック (Gradle wrapper vs. システム Gradle、.nvmrc vs. package.json engines、...) は一度エンコードされるため、エージェントがたまたま実行しようと思いついたものに依存するのではなく、セッション間で診断が一貫します。

• エージェントにシェルを渡すより安全。 任意のコマンド実行も、破壊的な操作も、決してありません -- セキュリティモデル を参照してください。

• シークレットに触れることはありません。 シークレットに見える環境変数は存在の有無のみチェックされ、値が読み取られたり返されたりすることはありません -- プライバシーモデル を参照してください。

• エージェントにシェルがない場所でも機能。 Bash ツールを持たない MCP クライアント (一部の IDE アシスタント、制限されたエージェント) でも、この機能をゼロではなく利用できます。

トークンコスト

推定ではなく実際の数値 -- このサーバー自身の MCP ツールスキーマ (mcp.list_tools()) と実際の dev_health() レスポンスから直接測定し、標準の約 4 文字 = 1 トークンの近似を使用しています。

トークンを消費するのは 2 つの異なるタイミングで、コストは大きく異なります:

ツールごとのスキーマ内訳 (測定値):

正直な結論: 環境の問題にそれ以外触れないセッションでの単発の診断では、生の Bash の方が総トークン数で安くなることがあります -- 約 1,400 トークンの固定スキーマ税が、複数のシェルコマンドを 1 回の呼び出しに置き換えることによる節約を上回ることが多いためです。両側の実際の数値については、以下の比較例を参照してください。

DevTwin のケースは、1 つのセッションで環境に関する質問が増えるほど強くなります (固定税は一度だけ支払われ、以降の質問は DevTwin では約 150 トークン、生の Bash では毎回数百トークン以上) -- そしてその真の利点は生のトークン数ではなく、一貫性、安全性、そして Bash ツールを持たない MCP クライアントで動作することです。利点 と 正直なトレードオフ を参照してください。

実用的な意味: DevTwin はユーザー全体ではなくプロジェクトごとに登録し、固定税が実際に役立つセッションでのみ支払われるようにしてください -- 別のプロジェクトでの使用 を参照してください。

正直なトレードオフ

DevTwin は安定した環境での日常使用ツールではありません -- 書くすべての関数で「Postgres が実行中か」を再確認する必要は誰にもありません。これは非常時用ツールです: 特定の瞬間 (新規クローン、謎のビルド失敗、コミット直前) に高い価値を発揮し、それ以外の時間はアイドル状態です。それが意図された使用パターンであり、欠点ではありません。

• トークンオーバーヘッドは、接続された瞬間から毎ターン支払われます。使用するかどうかに関係なくです -- 実際の測定値はトークンコストを参照してください。

• 単発の質問でトークン数が必ずしも有利になるわけではありません。一貫性、安全性、シェルを持たないクライアントへの到達性で勝ります -- 利点を参照してください。

• エージェントがすでに完全に管理下にあるリポジトリへのシェルアクセスを持ち、環境ドリフトがほとんどない場合、DevTwinはそこでは不要かもしれません。

• DevTwinが最も力を発揮するのは、共有/オンボーディング用リポジトリ、信頼度が低いまたはシェルなしのエージェント設定、そして「何を確認すればいいのか」自体が難しいマルチエコシステムのモノレポです。

DevTwinあり vs. なし：具体例

エージェントに「npm test が失敗するのはなぜ？」と尋ね、実際の原因がNodeバージョンの不一致とPostgresが起動していないことだとします。

DevTwinなし（生のBashを使うエージェント）-- 正しい手順を1コマンドずつ推測する必要があります：

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

6回の往復、エージェントが自分で考え出さなければならない調査経路、ステップ4で会話に秘密情報が漏れる現実的なリスク、そしておよそ400〜800トークンのコマンド+出力テキスト（ファイルサイズや実行中のDockerコンテナ数によって変動）。

DevTwinありなら、1回の呼び出しで：

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

同じ結論、応答は約150トークン -- さらに、そのターンですでに支払われている約1,400トークンの固定スキーマ税が加わります（トークンコストを参照）。6回の呼び出しが1回になり、秘密情報が漏れる可能性はゼロ、セッションごとに変わる自由形式の調査ではなく、毎回まったく同じキュレーション済みチェックが実行されます。

これで可能になる質問の例

• 「開発環境をチェックして。」

• 「Kotlinプロジェクトのビルドが失敗するのはなぜ？」

• 「このリポジトリに対してNodeバージョンは正しい？」

• 「アプリがPostgresに接続できないのはなぜ？」

• 「環境がこのリポジトリの期待値からドリフトしていない？」

• 「コミットする前に何を実行すべき？」

• 「このリポジトリをクローンしたばかり -- 実行するには何が必要？」

言語別の例

サポートされているエコシステムごとに1行：実際に尋ねる質問、その回答のためにDevTwinがチェックする内容、dev_check が認識するテスト/ビルドコマンド。

アーキテクチャ

1つのMCPサーバー、多数のエコシステムアダプター -- 言語ごとに別々のサーバーではありません。

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

詳細は docs/architecture.md を参照してください。新しい言語アダプターの追加方法：docs/adapters.md。

サポートされているエコシステム

特定のアダプターに一致しないプロジェクトでも、汎用アダプターから有用な出力が得られます -- DevTwinは認識できないプロジェクトに対して何も返さないことはありません。

インストール

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

このリポジトリのクローンに対するローカル開発については、docs/development.md を参照してください。

MCPクライアント設定

正確な設定構文はクライアントによって異なります -- お使いのクライアントのドキュメントを参照してください。一般的に、DevTwinはstdio MCPサーバーとして次のように起動されます：

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

クローンからのローカル開発用（パッケージをインストールしない場合）：

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

MCP Inspectorでツールの検出を確認：

npx @modelcontextprotocol/inspector uv run devtwin

別のプロジェクトでの使用（他の開発者向け）

DevTwinは単一のバイナリです -- 任意の数のプロジェクトを同じインストールに向けることができ、プロジェクトごとの再インストールは不要です。2つのスコープがあります：

プロジェクトスコープ -- プロジェクトルートに .mcp.json を配置：

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

またはClaude Code CLIを使用：

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

ユーザースコープ：

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

追加後、クライアントを再起動（またはMCPサーバーに再接続）してから、通常の質問をするだけです -- これで可能になる質問の例 を参照してください。

モノレポのヒント： 複数のプラットフォーム（例：Android + iOS + バックエンド）が混在するリポジトリでは、リポジトリルートではなく特定のサブフォルダーに向けて質問してください -- 例：「android/ アプリのヘルスをチェックして」。混在リポジトリのルートでの dev_detect は、見つかったすべてのエコシステムを報告します。これは一度は役立ちますが、対象を絞ったチェックにはノイズが多いです。

ツールリファレンス

すべてのツールは {status, summary, data, issues, recommendations} を返します。status は ok、warning、error、unknown のいずれかです。

セキュリティモデル

• 任意のコマンド実行はありません。 execute_shell ツールは存在しません。 dev_check は、DevTwin 自身がプロジェクトファイルから認識したコマンドのみを、 許可リストと照合し、shell=False と タイムアウト付きで実行します。

• 破壊的な操作は一切行いません。 DevTwin は git reset --hard、 rm -rf、kill -9、docker compose down、ロックファイルの削除、 または .env の変更を決して実行しません。

• dev_prepare は計画のみを行います。 提案されたすべてのステップを分類し (read_only/safe/requires_approval/dangerous)、自身では一切実行しません。

詳細: docs/security.md。

プライバシーモデル

• 環境変数は、名前がシークレットに見える場合 (PASSWORD、TOKEN、SECRET、API_KEY、 PRIVATE_KEY、ACCESS_KEY、AUTH、CREDENTIAL など) に存在のみが チェックされます。値が返されることはありません。

• .env ファイルは変数名のみがスキャンされます。

• dev_precommit は、シークレット風のステージングされたファイル名にフラグを立てますが、 その内容を読み取ったり報告したりすることはありません。

ローカルファーストアーキテクチャ

• サーバーコンポーネント、アカウント、独自のネットワーク呼び出しはありません。検査対象の ローカルコマンド (git、docker、言語ツールチェーン) のみを使用します。

• 報告されるすべての情報は、実行中のマシン上にすでにあるファイルとプロセスから取得されます。

開発

uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src
uv run devtwin

完全なワークフローについては docs/development.md を参照してください。

コントリビューション

CONTRIBUTING.md を参照してください。新しい言語エコシステム の追加が最も一般的なコントリビューションです。テンプレートは docs/adapters.md を、実際にマージされた例は src/devtwin/adapters/swift.py、 ruby.py、および php.py を参照して、あなたの実装のモデルにしてください。

ロードマップ

• 追加のエコシステムアダプター: Elixir、Dart、Scala、 C/C++ (CMake/Bazel/Buck)、Nix (追加方法は docs/adapters.md を参照)

• 追加のサービス検出器 (MySQL/MariaDB、MongoDB、Kafka、RabbitMQ)

• CI 設定に対するより詳細なドリフト比較 (例: GitHub Actions のランタイムマトリックス)

• セッション内のツール呼び出し間での高コストなチェックのオプションのローカルキャッシュ

ライセンス

Apache-2.0 -- LICENSE を参照してください。