Imperal MCP

imperal-mcp — ICNLI を活用した LLM と AI エージェントのためのスーパー・スイート 🐝

Python 3.7 – 3.14 · pip install "imperal-mcp[code]" は、どのバージョンでもすぐに動作します。

LLM を盲目のまま動かすのはやめましょう。 imperal-mcp は LLM のためのオールインワンのスーパー・スイート兼エクソスケルトンです。ライブの Tree-sitter AST コールグラフ、シンボルの精密な読み取り、見えない ShadowGit チェックポイント、クロスプラットフォームのクラウドメモリ、さらに ICNLI と Imperal Cloud を活用したフルスタックのクラウドアプリビルダーによって、Claude Code、Claude Desktop、Cursor、OpenAI Codex、Windsurf、Gemini CLI、Cline、Goose を強化します。

インストールは一度だけ。コーディングエージェントは コンテキストにファイル全体を丸ごと流し込まなくなり、1 回の呼び出しで見慣れないリポジトリを把握してナビゲートし、編集のたびに影響範囲と構文を自動チェックし、あらゆる IDE、ターミナル、チャット環境をまたいでアーキテクチャを記憶し、さらに Imperal Marketplace でフルスタックのクラウドアプリを構築、デプロイ、収益化できるようになります。

---

開発者がすぐに imperal-mcp に乗り換える理由

imperal-mcp を接続した瞬間、典型的な LLM コーディングセッションに何が起こるかをご覧ください。

WITHOUT imperal-mcp (Standard Agent Workflow)
  1. cat / Read 1,800-line service.py         -> 72,000 chars dumped into context
  2. grep -rn "process_Order" across repo     -> 140 noisy text matches
  3. Read 3 more full files to trace callers  -> +95,000 chars burned
  4. Edit shared function blind               -> breaks 2 callers & leaves syntax error
  5. Switch from Cursor to Claude Code        -> total amnesia; re-explain architecture from scratch

WITH imperal-mcp (The SuperSuite Exoskeleton)
  1. orient("process_order")                  -> repo profile + top ranked AST symbols in 1 call
  2. outline("service.py")                    -> compact structural map with exact line ranges
  3. read_symbol("service.py", "Order.run")   -> reads ONLY the 28 lines you need
  4. impact_of_change(["Order.run"])          -> lists every dependent file & caller before you touch a line
  5. PostToolUse hook -> check_syntax         -> catches syntax errors in milliseconds after every Edit/Write
  6. checkpoint("before-refactor")            -> instant ShadowGit snapshot outside .git (rollback in 1 call)
  7. recall_context / save_repo_note          -> every rule & repo note follows you across Claude, Cursor & Telegram

imperal-mcp が解消する 5 つの構造的ボトルネック

標準的な LLM ワークフローにおけるボトルネック	imperal-mcp SuperSuite が提供するもの	その違いをすぐに実感できる理由
不要なトークンとコンテキストの浪費 — エージェントは、単一の関数を確認するだけなのに、数千行に及ぶファイル全体や生の grep 出力をコンテキストウィンドウに読み込みます。	精密な AST と呼び出しグラフのスライス（outline、read_symbol、graph_slice、contract_slice）により、要求されたシンボルの定義、シグネチャ、呼び出しエッジだけを返します。	コンテキストウィンドウを鋭く保ちます — 2,000 行のノイズの代わりに、AST で検証済みのコードを 30 行読み込み、token_savings() で正確な削減量を監査できます。
時間のかかる反復的な全体把握 — 新しいタスクのたびに、モデルがプロジェクトの構成を理解するまで、find、ls、grep、cat の呼び出しを何度も順番に行います。	一度で完了する構造的な全体把握（orient、repo_profile、search_code、coding_context）により、実際のコードグラフから言語、エントリーポイント、テストランナー、ランキングされたシンボルを把握できます。	コールドスタートの遅延はゼロ — エージェントは最初のターンでリポジトリのアーキテクチャを理解します。
ツール間でのコンテキスト喪失と記憶忘れ — Cursor から Claude Code に切り替えたり、ターミナルから Web やモバイルに移ったりすると、LLM はアーキテクチャ、ルール、決定事項を忘れてしまいます。	プラットフォーム横断の統合クラウドメモリ（recall_context、remember_fact、save_repo_note）により、ユーザー指示と引用付きのリポジトリノートを、すべての MCP クライアント、Imperal Web Panel、Telegram の間で同期します。	同じことを繰り返し伝える必要はありません — 使用するすべての環境とモデルで、永続的なエンジニアリングの頭脳を 1 つ共有できます。
共有コードを壊す不安 — LLM は下流の呼び出し元やコントラクトを確認せずに共有ヘルパーを変更し、複数ファイルにわたる実験が失敗すると .git を汚してしまいます。	影響範囲の計算と ShadowGit スナップショット（impact_of_change、check_syntax、checkpoint、checkpoint_diff、checkpoint_rollback）により、編集前に依存先を検証し、.git の外に作業ツリーのスナップショットを作成します。	自信を持ってリファクタリングできます — 編集前に呼び出し元を把握し、git log に触れることなく失敗した実験をロールバックできます。
行き詰まるローカルスクリプト — ほとんどの MCP サーバーは単一の API をラップするだけなので、ワークフローを再利用可能なアプリや収益源に変えることはできません。	フルスタックアプリビルダーとマーケットプレイスでの収益化（validate_ir、smoke_ir、deploy_ir、run_read_tool、run_write_tool、upload_file）により、Imperal Marketplace でクラウドアプリを構築、デプロイ、収益化できます。	ワークフローを収益に変えます — 自分、チーム、または Imperal エコシステム全体のためにクラウド拡張機能を構築できます。

---

SuperSuite の 5 つのコアピラー

1. 精密なコンテキストと正確なトークン使用量の計測（AST シンボルスライス）

無関係なコードを何千行も LLM のコンテキストウィンドウに詰め込むと、トークンを浪費し、最初のトークンが出力されるまでの時間を遅らせ、推論の精度を低下させます。

• まず全体を把握し、必要なものだけを読む：1,500 行のモジュール全体をコンテキストに読み込む代わりに、エージェントは outline(path) を呼び出して、クラス、メソッド、関数の構造を正確な行範囲とともにコンパクトに確認し、その後 read_symbol(path, "ClassName.method")（または L120-180）を呼び出して対象の範囲だけを読み込みます。
• 正確なディスク上の計測値（token_savings()）：セッション中の任意の時点で token_savings() を呼び出すと、実測された正確な文字数と行数（returned_chars 対 baseline_chars、returned_lines 対 baseline_lines、baseline_files、ツールごとの内訳）を確認できます。ベースラインは、ディスク上にある実際に一致したファイルから直接計測されます（baseline_basis: "matched_files_on_disk"）。リポジトリ全体や架空の倍率を使って水増しすることはありません。

2. ライブコードグラフ、呼び出しコントラクト、影響範囲の分析

imperal-mcp[code] をインストールすると、サーバーは増分更新される Tree-sitter AST と依存関係グラフを維持します（Python の構文チェックとアウトラインが最小限の環境でも機能するよう、組み込みの Python ast フォールバックも備えています）。

• orient(query) — リポジトリのプロファイルと、タスクに関連度の高いシンボルおよびコードの一致箇所を組み合わせた、1 回の呼び出しでタスクに取りかかれる機能です。
• repo_profile() と coding_context() — 言語、ファイル数、アーキテクチャ上のハブ、テストコマンドのヒント、Git 作業ツリーの状態をすぐに確認できます。
• search_code(query, kind, path_glob) — インデックス化されたワークスペース全体から、シンボル検索、セマンティック検索、字句検索を組み合わせて検索します。
• graph_slice(symbols, depth) — シンボルの定義、シグネチャ、直接の呼び出し元、呼び出し先をまとめて取得します。
• contract_slice(symbols) — 正確な関数シグネチャ、戻り値のアノテーション、発生する例外、実際の呼び出し箇所での引数の形を確認します。
• impact_of_change(symbols) — 編集を始める前に、変更対象のコードに依存する下流のファイルと呼び出し元のシンボルをすべて算出します。
• check_syntax(path) — 編集のたびにすぐに構文を検証できます。また、Claude Code 用の PostToolUse フックをオプションで自動設定できます。

3. あらゆるプラットフォームとインターフェースで、永続的なメモリーとコンテキストを共有

アーキテクチャに関する知識を、単一の IDE タブやモデルベンダーに閉じ込める必要はありません。

• remember_fact(fact, category, tags) — 継続的なエンジニアリングルール、ユーザーの好み、運用上の指示を Imperal Cloud Memory に保存します。
• save_repo_note(note, repo, citations) — リポジトリの慣習、ビルドコマンド、アーキテクチャの不変条件を、プロジェクトにひも付けて記録します。
• recall_context(query) — MCP 互換クライアント（Claude Code、Cursor、Windsurf、Codex、Gemini CLI）、Imperal Web Panel、または Telegram から、関連するユーザー情報やリポジトリのメモを取得します。

4. Imperal Marketplace でアプリを構築、デプロイ、収益化

ICNLI (Infrastructure Contextual Natural Language Interface) を基盤とする imperal-mcp は、完全な クラウドアプリケーション SDK と実行エンジンです。

• 自然言語でフルスタックのクラウドアプリを作成：組み込みの MCP リソース（imperal://ir-spec、imperal://ui-catalog、imperal://examples）と build_imperal_app プロンプトを使って、LLM が指示を宣言型の Imperal 中間表現（app.ir.json） バンドルにコンパイルします。UI ビュー、状態スキーマ、コネクター、型付きツールハンドラーが含まれます。
• 数秒で検証、スモークテスト、デプロイ：
  1. validate_ir(app_ir) — IR の構造と、宣言されたすべてのステップをローカルで静的に検証します。
  2. smoke_ir(app_ir, function, args) — Imperal Cloud 上の分離されたサンドボックスストア内でライブのドライランを実行し、{ok, result, trace} を確認します。
  3. deploy_ir(app_ir, app_id) — 検証済みのアプリを Imperal Cloud アカウントに直接デプロイします。
• Imperal Marketplace で公開して収益化：アプリのデプロイとテストが完了したら、Imperal Marketplace で公開し、カスタム SaaS コネクター、DevOps 自動化、分析スイート、各分野に特化したワークフローを、ほかの開発者や企業と共有、または販売できます。

5. 見えない ShadowGit セーフティネットと機能ゲート付きクラウド実行

• ShadowGit チェックポイント（checkpoint、checkpoint_diff、checkpoint_rollback）：リスクの高いリファクタリングの前に、実際の .git 履歴に煩雑な WIP コミットを作成することなく、ワークスペースのスナップショットを分離された ShadowGit ストアに保存します。任意の時点で差分を比較したり、実験に失敗した場合にロールバックしたりできます（checkpoint_rollback は明示的に破壊的操作としてマークされているため、作業ファイルを上書きする前に MCP クライアントが確認を求めます）。
• ワークスペース境界の保護：すべてのローカルコードおよびファイルツールは、厳密なワークスペースパス解決を適用します。設定されたワークスペースルート外のパスや root ディレクトリ（~/.zshrc や /etc など）を対象とするリクエストは、OutsideWorkspaceError で拒否されます。
• 3 段階のクラウド安全性（read ／ write ／ destructive）：
  • run_read_tool は読み取り専用の操作を実行し、応答から PII を自動的に除去します。
  • run_write_tool は標準的な書き込みツールを直接実行し、destructive ツールには対話型の人間による同意（MCP エリシテーション）を求め、金銭や財務に関する操作には帯域外のパネル承認を適用します。

ツールとリソースの全カタログ（ツール 25 個 ＋ リソース 5 個）

ローカルコードインテリジェンスと呼び出しグラフ（imperal-mcp[code]）

ツール	読み取り専用	破壊的	説明
orient(query, root?)	はい	いいえ	1 回の呼び出しでタスクの状況を把握：リポジトリのプロファイル（files、languages、git、test_hints、sample_symbols）と、query に対する上位の意味検索および字句検索のコード一致結果を組み合わせます。
repo_profile(root?)	はい	いいえ	ファイル数、言語の分布、現在の git ref、テストランナーのヒント、主要なエントリーポイントのシンボルを含む、構造化されたリポジトリの概要を返します。
search_code(query, k?, path_glob?, kind?, root?)	はい	いいえ	インデックス化されたワークスペース全体を対象に、意味検索、字句検索、シンボル検索を組み合わせたハイブリッド検索を行います（kind：all、symbol、file）。
outline(path, root?)	はい	いいえ	ファイル本体全体を読み込まずに、ソースファイルの構造マップ（クラス、関数、メソッド、主要な領域と正確な 1 始まりの行範囲）を作成します。
read_symbol(path, name, root?)	はい	いいえ	1 始まりの行番号を使い、特定の関数、クラス、メソッド（Class.method）、または行範囲（L10-50）のみを読み込みます。
graph_slice(symbols, depth?, root?)	はい	いいえ	1 つ以上のシンボルについて、ライブ AST 呼び出しグラフから定義位置、シグネチャ、直接の呼び出し元、直接の呼び出し先を返します。
contract_slice(symbols?, query?, kind?, k?, root?)	はい	いいえ	検証済みのシンボルコントラクト（定義、シグネチャ、呼び出し箇所の根拠）を 1 回の呼び出しで抽出します。
impact_of_change(symbols, root?)	はい	いいえ	下流への影響範囲を計算します。変更予定のシンボルを呼び出す、またはそれらに依存するすべてのファイルとシンボルを特定します。
check_syntax(path, root?)	はい	いいえ	編集後のソースファイルの構文を検証します（複数言語の AST には Tree-sitter を使用し、Python には ast、JSON には標準ライブラリの検証を使用します。未対応のファイル形式では supported: false, clean: null を返します）。
coding_context(root?)	はい	いいえ	git ブランチ、HEAD、変更のある作業ツリーファイル、最近のコミットを返し、状況をすぐに把握できるようにします。
token_savings()	はい	いいえ	ディスク上の実際に一致したファイルを基準とした、セッションの文字数と行数の実測値を報告します（baseline_basis: "matched_files_on_disk"、baseline_files、returned_chars、baseline_chars、saved_chars、returned_lines、baseline_lines、saved_lines、compression_pct、by_tool）。

ローカル ShadowGit チェックポイント（imperal-mcp[code]）

ツール	読み取り専用	破壊的	機能
checkpoint(label?, touched_paths?, root?)	いいえ	いいえ	.git の履歴に触れることなく、ワークスペースの状態を分離された ShadowGit ストアにスナップショットとして保存します。
checkpoint_diff(target?, root?)	はい	いいえ	現在の作業ファイルと ShadowGit チェックポイント（step 番号または ref）の間の統合差分を表示します。
checkpoint_rollback(target?, root?)	いいえ	はい	ShadowGit チェックポイントからワークスペースのファイルを復元します（destructiveHint=True により、作業ファイルを上書きする前に MCP クライアントが確認を求めます）。

クロスプラットフォームのクラウドメモリ（Imperal Cloud）

ツール	読み取り専用	破壊的	機能
recall_context(query?, category?, limit?)	はい	いいえ	Imperal Cloud（memory-index）から、永続的な運用ルール、アーキテクチャ上の決定事項、ユーザーの好み、各種サーフェスをまたぐ事実を呼び出します。PII は自動的にスクラブされます。
remember_fact(fact, category?, tags?)	いいえ	いいえ	Terminal、Web Panel、Telegram 間で共有される統合 Imperal Cloud メモリに、永続的な事実、運用ルール、またはユーザーの好みを保存します。
save_repo_note(note, repo?, citations?)	いいえ	いいえ	出典（file:line）付きのアーキテクチャまたはリポジトリに関するメモを Imperal Cloud メモリに保存します。

Imperal Cloud アプリビルダー、サンドボックス、実行（ICNLI）

ツール	読み取り専用	破壊的	機能
validate_ir(app_ir)	はい	いいえ	app.ir.json バンドル（ir_version: "1.0"、state、views、handlers）のオフライン構造・セマンティック検証を行います。
smoke_ir(app_ir, function, args?)	はい	いいえ	Imperal Cloud 上の分離されたサンドボックスストア内でハンドラーをステップごとに実行し、{ok, result, trace} を返します。
deploy_ir(app_ir, app_id?)	いいえ	いいえ	app.ir.json アプリケーションを検証し、Imperal Cloud アカウントにデプロイします。
list_apps()	はい	いいえ	Imperal Cloud アカウントにインストール済みおよび利用可能なすべてのアプリを、{id, name, version, description, category, status} とともに一覧表示します。
get_app(app_id)	はい	いいえ	アプリの完全なマニフェスト、ツールスキーマ、および action_type の分類（read / write / destructive）を返します。
run_read_tool(app_id, function, params?)	はい	いいえ	read 階層のクラウドツールを実行し、応答からPII（email、phone、ssn、card、jwt、api_key、iban）をスクラブします。
run_write_tool(app_id, function, params?)	いいえ	はい	write ツールを直接実行し、destructive ツールでは対話型の人間による同意（approve_once / autopilot / reject）を求めます。また、パネルでの確認を優先し、直接の送金をブロックします。
upload_file(path, name?)	いいえ	いいえ	ローカルファイルを Imperal Cloud ストレージにアップロードし、クラウドツール呼び出しで使用する storage:// URI を返します。

組み込み MCP リソース

リソース URI	内容
imperal://exoskeleton-protocol	LLM 向けの運用規律です。まず状況を把握し、AST を厳選して読み取り、影響範囲を確認し、構文を検証します。
imperal://ui-catalog	app.ir.json のビューで利用できる17種類の宣言型UIコンポーネントのリファレンスです。
imperal://ir-spec	app.ir.json のエンベロープ、state スキーマ、および17種類の決定論的なハンドラーステップの完全な仕様です。
imperal://examples	実行可能な app.ir.json のリファレンスアプリケーション一式です。
imperal://build-prompt	Imperal アプリの設計、検証、スモークテスト、デプロイを行うための、手順ごとのシステムプレイブックです。

---

インストールとクイックスタート

1. パッケージをインストールする

# Full SuperSuite (Cloud + Local AST Code Graph, Call Graph, Search & ShadowGit)
pip install "imperal-mcp[code]"

# Lightweight Cloud-only install (App Builder, Cloud Tools & Cross-Surface Memory)
pip install imperal-mcp

Python 3.7～3.14 との互換性：Python 3.10 以降では、imperal-mcp がネイティブに動作します。古いシステムの Python（3.7～3.9）では、依存関係ゼロの _launch.py ブートストラッパーが、初回起動時に uv を介して分離された Python 3.12 ランタイムを自動的に用意し、imperal-mcp[code]==<version> をインストールします。そのため、レガシーシステムでも AST & Call-Graph Exoskeleton 全体をシームレスに利用できます。

2. Imperal Cloud で認証する（Cloud Memory と Apps 用）

imperal-mcp login

これにより、Imperal Cloud（api / gateway）に対するブラウザー経由の OAuth 2.0 Device Authorization + PKCE フローが開始され、認証情報が ~/.config/imperal/credentials.json に 0600 の権限で保存されます。（ローカルのコードインテリジェンスツールは、ログイン前でもオフラインで動作します。）

3. LLM クライアントを接続する

オプション A：Claude Code のワンコマンドセットアップ（推奨）

プロジェクトリポジトリ内で実行します。

imperal-mcp claude-setup --with-hooks

このコマンドは安全かつ冪等に、次の処理を行います。

• .mcp.json に imperal サーバーを追加します（既存の mcpServers エントリーを保持し、不正な JSON ファイルへの上書きを拒否します）。
• IMPERAL-MCP-EXOSKELETON の運用セクションを CLAUDE.md に追記します（既存のプロジェクト指示をすべて保持します）。
• claude-setup の実行に使用されたものと同一の Python 環境バイナリを使って、.claude/settings.local.json に PostToolUse フックをインストールします。Edit、MultiEdit、または Write の実行後に、このフックが check_syntax を実行し、構文エラーがあれば終了コード 2 とともに stderr に報告します。これにより、Claude Code は壊れた構文をすぐに検出して修正できます。

オプション B：Claude Code CLI

claude mcp add imperal -- imperal-mcp

オプション C：Cursor / Claude Desktop / Windsurf / Cline（.mcp.json または claude_desktop_config.json）

{
  "mcpServers": {
    "imperal": {
      "command": "imperal-mcp",
      "args": [],
      "env": {
        "IMPERAL_WORKSPACE": "/absolute/path/to/your/repo"
      }
    }
  }
}

オプション D：OpenAI Codex / Gemini CLI / Goose

MCP 互換の stdio クライアントを、IMPERAL_WORKSPACE にリポジトリのルートを設定したうえで、imperal-mcp 実行ファイルに接続します。

---

CLI リファレンス

imperal-mcp                  # Start the MCP server over stdio
imperal-mcp login            # Sign in via browser (Device Code + PKCE); supports --no-browser
imperal-mcp logout           # Revoke refresh token and delete local credentials
imperal-mcp claude-setup     # Configure .mcp.json and CLAUDE.md (--workspace, --with-hooks)
imperal-mcp install-hooks    # Install PostToolUse syntax-check hook in .claude/settings.local.json
imperal-mcp hook             # Run a Claude Code hook event handler (post-tool-use)
imperal-mcp status           # Print JSON readiness and repository profile for --workspace

---

アーキテクチャとセキュリティ保証

1. パブリッククラウドのトポロジ（api、gateway、worker）： すべてのクラウドリクエストは、HTTPS 経由で Imperal Cloud の api および gateway エンドポイントと通信し、分離されたアプリの実行とサンドボックスのスモークテストを worker ランタイムにディスパッチします。
2. 厳格なワークスペース内制限： すべてのローカルツールは、os.path.realpath を使ってパスと root の上書きを解決し、os.path.commonpath([workspace_root, candidate]) == workspace_root であることを検証します。ワークスペース外を読み取ろうとすると、OutsideWorkspaceError が発生します。
3. 設定ファイルの完全性： claude-setup と install-hooks は、既存の .mcp.json と .claude/settings.local.json を厳密に解析します。ユーザーファイルに JSON 構文エラーがある場合、既存の設定を消去する代わりに、CLI は上書きを拒否します。
4. PII の防御的スクラブ： すべてのクラウド読み取りデータとメモリのペイロードは defensive_scrub を通過し、モデルコンテキストに入る前にメールアドレス、電話番号、SSN、決済カード、JWT、API キー、IBAN がマスキングされます。

---

ライセンス、プロトコル、商標

• コードライセンス：GNU General Public License v3.0 (GPL-3.0-only) のもとでライセンスされています。
• プロトコル仕様：ICNLI (Infrastructure Contextual Natural Language Interface) を基盤としており、CC BY-SA 4.0 のもとでライセンスされたオープン仕様です。
• プライバシーポリシー：ローカル実行、認証情報の保存、PII のマスキングについては PRIVACY.md をご覧ください。
• 商標および帰属表示： Imperal、Imperal Cloud、Webbee、ICNLI は Imperal, Inc. の商標です。 Claude、Claude Code、Claude Desktop、Anthropic は Anthropic, PBC の商標です。Cursor は Anysphere, Inc. の商標です。OpenAI と Codex は OpenAI, Inc. の商標です。Windsurf は Exafunction, Inc.（Codeium）の商標です。Gemini は Google LLC の商標です。サードパーティの製品名および会社名は、MCP との相互運用性および互換性を示す目的でのみ使用しており、推奨や提携を示すものではありません。