Itamos MCP Tools

Itamos MCP ツール

ギリシャで生まれ、世界へ。 AGPL-3.0 のもとで無料かつオープンソースです。クローズドソースでの利用には商用ライセンスをご用意しています。

---

課題

あらゆる LLM コーディングアシスタントが同じ壁に直面します。コードベースは大きすぎてコンテキストに収まりません。一般的な対応は、ファイルをダンプすることです。よさそうなものを grep で探し、cat で読み込み、うまくいくことを願います。ファイルが 50k 件では破綻し、240k 件ではそもそも機能しませんでした。

私たちは、コードベースへの生のファイルアクセスの代わりに、LLM がコードベースを構造的に把握できる 4 つのツールを開発しました。さらに、コードを取り込むためのサンドボックス化された git も用意しています。その結果、シニアエンジニアのようにコードをナビゲートするモデルが実現します。まずアーキテクチャから始め、モジュールへと絞り込み、必要なセグメントだけを読み込みます。1 回の呼び出しでプロジェクトから必要な行へ直接たどり着き、保存するたびに反映前のチェックが行われます。

論文全文を読む： docs/PAPER.md：各ツールの仕組み、その設計理由、ホスト型サンドボックスの動作を図解付きで説明しています。

---

ツール

ツール	機能
read_file	唯一のエントリーポイントです。パスを指定しないとプロジェクト一覧を表示します。プロジェクト名を指定すると座標付きの構造を表示し（コードは表示しません）、座標を指定すると 1 回の呼び出しでファイルマップまたは 1 つのセグメントを開きます。一度に 1 つのセグメントを編集し、保存するたびに自動で検証します。
master_architect	read_file の基盤となるエンジンです。コードベースをグラフ（ファイル、インポート、データベース、サーバー）にインデックス化し、保存のたびに同期します。サンドボックス内では直接呼び出されず、read_file が処理します。
write_file	新しいファイルのみを作成し、上書きはしません。編集には read_file を使用します。新しいファイルはすべて、エージェントが指定したプロジェクトに属します。既存のプロジェクトでも、新しいプロジェクトを開始するための新しい名前でも指定できます。自動で配置されることはありません。
git	セキュリティのためにサンドボックス化された、従来の Itamos git ツールです。clone（リモート URL のみ、depth=1）、status、commit を利用できます。クローンが完了すると、すぐにプロジェクトとしてスキャンされます。すべてセッションのワークスペース内にとどまり、push は利用できません。
web_skeleton	LLM を第一に考えたウェブ認識機能です。生の HTML と比べてトークンを 97% 削減します。アクション：search、skeleton、read、click。

通常のシェルワークフロー（grep、cat、run_cmd）と比べて、トークンを少なくとも 97% 削減します。モデルが 1 回の試行でバグを修正できる最良のケースと比較して測定しています。生のシェルアクセスでよくある失敗した試行は含まれないため、実際のセッションではさらに節約できます。

---

仕組み

セッションモデル

各クライアントには独立したワークスペースが割り当てられます。状態の共有やセッション間の漏えいはありません。ワークスペースは 10 分間操作がないと消去されます。

ナビゲーション：プロジェクト → ファイル → セグメント

read_file()                                            → your projects
read_file(path="itsdangerous")                         → the structure: folders and files with coordinates, no code
read_file(path="itsdangerous", segment="d.a.f")        → the map of signer.py, one line per segment
read_file(path="itsdangerous", segment="d.a.f.31.17")  → the code of verify_signature, nothing else

座標：英字は場所を示します（フォルダーとファイルは、各フォルダー内で同じ順序を共有します）。数字はファイル内の要素を示します。d.a.f.31.17 は src → itsdangerous → signer.py → セグメント 31.17 を表します。一度もスキャンされていないフォルダーは、初めて読み込む際にスキャンされます。クローンしたリポジトリは、クローンの完了直後にスキャンされます。

すべてをダンプすることはありません：構造またはファイルマップが約 3,000 トークンを超える場合は、概要を返し、検索語を指定するよう求めます。search はどちらにも対応し、プロジェクト内のファイル名とフォルダー名、またはファイル内のセグメント名を検索します。trace=true を指定すると、ファイルがどこに接続しているか、またはプロジェクトのデータフローを表示します。

セグメント

ファイルは名前付きのセグメントに解析されます。5,000 行のファイルには 40 個のセグメントが含まれることがあります。ファイルマップにはセグメントごとに 1 行が割り当てられ、クラスにはメソッドが列挙されます。モデルはマップを読み、必要なセグメントを選んで、そのセグメントを読み込みます。コンテキストの使用量は、5,000 行ではなく、およそ 120 行分です。

編集と検証

一度に1か所だけ編集し、最後の変更以降にモデルが読み込んだセグメントだけを対象にするため、確認していないコードを変更することはありません。保存前にファイルを検証します。

レベル	チェック内容	失敗時
L1	構文：tree-sitter と各言語固有のチェッカー（py_compile、node --check、php -l、bash -n、gofmt、プロジェクトのコンテキストでの C/C++、設定パーサー）	保存されません。エラーで行が示されます
L2	設定ファイルをサービス固有のチェッカーで検証（nginx -t、sshd -t、visudo、systemd-analyze）。リンターも実行されます	設定エラー：保存されません。リンターの指摘は報告のみです
L3	接続：すべてのローカルインポートがプロジェクト内のファイルに解決されること（Python と JavaScript/TypeScript：その他のインポートはインストール済みパッケージであること。Python はプロジェクトに仮想環境がある場合、その環境内で確認）；SQL は稼働中のデータベーススキーマと照合してチェック	未完了の内容と確認方法を示したうえで保存されます。これにより、プロジェクトの最初のファイルから、まだ存在しないファイルをインポートできます

L3 は古いインデックスではなく、保存する内容をチェックします。また、保存のたびに、サポート対象のすべての言語でファイルを再インデックスするため、マップがディスク上の状態に遅れることはありません。

web_skeleton によるトークン削減

最新のウェブページの生 HTML は 50,000～200,000 トークンになります。web_skeleton の出力は 500～3,000 トークンです。モデルはスケルトンを読み、必要なセクション ID を選び、そのセクションだけを読み込みます。

---

ベンチマーク

Claude Opus 5.5 と Claude Sonnet を使った実運用で検証済みです。MCP 対応モデルであれば、どれでもツールを使用できます。

私たちの言葉を鵜呑みにしないでください。ホスト型サンドボックスで、ご自身のモデルとリポジトリを使ってツールを無料でテストし、結果を Discussions → Benchmarks に投稿してください。モデル、タスク、トークン数、所要時間を記載してください。

バグを見つけましたか？ 再現手順を添えてイシューを作成してください。報告の一つひとつがツールの改善につながります。

---

接続

サンドボックスサーバーは、SSE をサポートする標準の MCP over HTTP POST に対応しています。

あらゆる MCP クライアントと互換性があります。実際には、Claude.ai と直接 API 連携（当社のベンチマークハーネス）で使用しています。

Claude で試す（無料のライブアルファ版）： https://mcp.itamos-technologia.com/mcp をコピーし、Claude のコネクター設定を開いて、Add custom connector をクリックし、アドレスを貼り付けて Add をクリックします。ボタンが1つあるページが開きます。Create my sandbox をクリックしてください。アカウントもメールアドレスも不要です。チャットで有効にし（+ → Connectors）、たとえば 「bbc.com/news にアクセスして、トップニュースを教えてください」 と尋ねます。他の MCP クライアントでは、同じアドレスをリモート MCP サーバーとして追加します。サンドボックスは10分間操作がないと削除されるため、機密データには使用しないでください。

---

セルフホスティング

要件

• ZFS を備えた Linux（必須）。 各サンドボックスは、ハードサイズ制限（クォータ）と圧縮が設定された独自の ZFS データセットです。これにより、他のユーザーが使うディスク領域まで、ユーザーが使い切ってしまうことを防ぎます。サーバーは起動時にこれを確認し、条件を満たさない場合は起動しません。
• Node.js 20 以降と、ネイティブモジュール用のビルドツール（Debian/Ubuntu：apt install build-essential python3）。
• git ツール用の git と、web_skeleton 用の Chrome または Chromium。

インストール

git clone https://github.com/itamos-technologia/itamos-mcp-tools.git
cd itamos-mcp-tools
npm install

npm install を1回実行するだけで、ツールフォルダーを含め、すべてがセットアップされます。

Ubuntu 26.04 では、代わりに Releases からパッケージをインストールできます：sudo apt install ./itamos-mcp-tools_1.1.0_all.deb。サービスユーザー、systemd サービス、/etc/itamos-mcp-tools/env の設定、および itamos-mcp-create-slots コマンドがセットアップされ、その後、次に行う2つの手順が表示されます。

追加の言語パーサー

標準の tree-sitter 文法（npm install でインストール）に加えて、read_file とセグメンターは grammars/ フォルダーの追加パーサーを使用します。

ファイル	パーサー	フォールバック先
.cu .cuh .hip	tree-sitter-cuda-plus	標準の tree-sitter-cuda、次に C++
.metal	tree-sitter-metal-plus	tree-sitter-metal、次に C++
.cpp .cc .hpp、C++ の .h	tree-sitter-cpp-plus	標準の tree-sitter-cpp
.m .mm、@interface を含む .h	tree-sitter-objc	C / C++

「plus」パーサーは標準文法に C++ の追加ルールを加えたもので、標準文法で解析できる箇所は同一の構文木になることを確認済みです。パーサーが見つからない場合や読み込みに失敗した場合はスキップされ、致命的なエラーにはなりません。

• Linux x64：作業不要です。 パーサーは grammars/tree-sitter-*/prebuilds/linux-x64/ にビルド済みの状態で同梱されています（Node-API、Node 18 以降、glibc 2.14 以降）。残りのセットアップは npm install が行います。
• その他のプラットフォーム（macOS、Windows、ARM）：各パーサーを一度コンパイルしてください。Python と C/C++ コンパイラーが必要です。

  cd grammars/tree-sitter-cuda-plus && npx node-gyp rebuild   # same for tree-sitter-cpp-plus, -metal-plus, -metal
  

• そのまま配置可能： grammars/tree-sitter-* の各フォルダーは、自己完結型のパッケージです。フォルダーをコピーするだけで、サンドボックスが名前から見つけるため、インストールやシンボリックリンクは不要です。文法を別の場所に置く場合は、SANDBOX_GRAMMARS_DIR を設定してください。
• 再生成：（grammars/plus/ のルールを変更した場合のみ）grammars/plus/build_plus.sh は tree-sitter-cli 0.25.10（ABI 15）で生成、コンパイルし、対応する tree-sitter-* フォルダーに配置します。引数はスクリプトのヘッダーに記載されています。

サンドボックススロットを作成する

sudo scripts/create-slots.sh tank/sandboxes 500 2G $USER

これにより、ZFS データセット tank/sandboxes の下に slot_001 から slot_500 までが作成されます（プール名はご自身の環境に合わせてください）。各スロットには 2 GB のクォータと lz4 圧縮が設定され、サーバーの実行ユーザーが所有します。再実行しても安全です。

起動

SANDBOX_ROOT=/tank/sandboxes SANDBOX_TOTAL_SLOTS=500 npm start

同じマシンから、MCP クライアントに http://localhost:4200/mcp をコネクターとして追加してください。ローカル接続は IP アドレスで識別されるため、サインインは不要です。

公開する

ファイアウォールでポート 4200 を開放し、 HTTPS リバースプロキシ（nginx など）を前段に配置して、X-Forwarded-For と X-Forwarded-Proto を設定してください。プロキシ経由のリクエストでは匿名のワンクリックサインインが使用されるため、共有アドレス（claude.ai など）を使うユーザーもそれぞれ専用のサンドボックスを利用できます。ポート 4200 への直接接続ではサインインが省略されるため、外部からそのポートに接続できないようにする必要があります。

テキストモデル（任意）

read_file と web_skeleton は、小型の要約モデルを使って、タイトルのない段落やページセクションに5～10語の短いタイトルを付けます。これにより、エージェントは内容を読まなくても各部分を見分けられます。要約モデルがなくてもすべて正常に動作し、その場合は各部分の最初の行が名前として使われます。

ITAMOS_SUMMARIZER_URL（デフォルトは http://127.0.0.1:8090）で設定できる、OpenAI互換のチャットエンドポイントであれば何でも使えます。単一の llama-server、Ollama、または複数の GPU の前段に置く同梱ルーターが使えます。段落全体が常に送信され、途中で切り詰められることはありません。

ホスト型サンドボックスでは、3台の GPU（16 GB の MI50 1台と8 GB の V340 ダイ2基）上で、Gemma 4 E4B（Q4_0）を要約モデルとして、EmbeddingGemma 300M を埋め込みモデルとして実行します。各要約モデルは次のように起動します。

llama-server -m gemma-4-E4B-it-Q4_0.gguf -ngl 99 --port 8190 \
  -np 64 -c 524288 --kv-unified -fa on --cache-type-k q4_0 --cache-type-v q4_0 -rea off

• --kv-unified：KVプールを共有するため、各リクエストは必要なトークン数だけを使用します。
• --cache-type-k q4_0 --cache-type-v q4_0（-fa on が必要）：4ビットのKVキャッシュです。このモデルではトークンあたり約4.5 KBです。
• -c はトークン単位のプールサイズです。MI50では524,288、各V340ダイでは262,144（32スロット）です。

ルーター（router/llm-router.js、サービス itamos-llm-router）は8090（要約モデル）と8091（埋め込みモデル）で待ち受けます。リクエストを送信する前に、バックエンド独自のトークナイザーでトークン数を数え、プールに空きのあるGPUに送信します（重み付けにより高速なGPUを優先します）。空きのあるGPUがない場合は、順番待ちにします。GPUが失敗すると15秒間そのGPUをスキップし、リクエストを別のGPUに再試行します。ROUTES で設定します（パッケージ内では /etc/itamos-mcp-tools/router.env）。GET /router/status では各GPUのプール、予約済みトークン数、キューを確認できます。

8091の埋め込みモデルは他のItamosサービスで使用されています。ツールでは、まだ埋め込みを使用していません。

設定

変数	デフォルト	説明
SANDBOX_ROOT	/fast/sandboxes	スロットのデータセットを格納するフォルダー
SANDBOX_TOTAL_SLOTS	500	スロット数
SANDBOX_PORT	4200	サーバーが待ち受けるポート
SANDBOX_TTL_MINUTES	10	サンドボックスが空にされるまでのアイドル時間（分）
SANDBOX_DATA_DIR	./data	サインインデータの保存場所（ハッシュ化されます）
PUBLIC_BASE_URL, PUBLIC_MCP_URL	プロキシヘッダーから取得	プロキシから取得できない場合に使用する公開アドレス
WEB_SKELETON_PUBLIC_ONLY	オフ	公開サーバーでは 1 に設定します。web_skeleton はプライベートアドレスとローカルアドレスを拒否するようになります
ITAMOS_SUMMARIZER_URL	http://127.0.0.1:8090	タイトル生成用の要約モデル（OpenAI互換のチャットエンドポイントであれば何でも使用可能）。空にするとタイトル生成が無効になります
ITAMOS_SUMMARIZER_MODEL	summarizer	各リクエストで送信されるモデル名です。実際のモデル名が必要なのはOllamaのみです
SANDBOX_SMTP_CREDENTIALS	Itamosサーバー上のパス	任意の「サンドボックスの準備ができました」メール用のJSONファイル（email、app_password、smtp_server、smtp_port）。設定しない場合、メールは送信されず、サーバーが理由をログに記録します。
ITAMOS_COSTS_DB	Itamosサーバー上のパス	トークン節約量の統計用SQLiteファイルです。書き込みできない場合、統計の記録はスキップされます。

---

ライセンス

デュアルライセンスです。AGPL-3.0 のもとで無料で使用、変更、共有できます。ネットワーク経由での使用も含め、変更したバージョンのソースを公開する必要があります。クローズド製品に組み込む場合は、商用ライセンスによってAGPLの義務が免除されます。[email protected] までお問い合わせください。

---

概要

ギリシャのトリカラにあるItamos Technologiaの創業者、Konstantinos Karamperis が設計・開発しました。産業工学とインフラストラクチャの経歴を持つシステムアーキテクトとして、AMDハードウェアとオープンソースの推論スタックを活用し、AIネイティブな開発者向けツールを構築しています。

LinkedIn · itamos-technologia.com