CostAffective-MCP

プラットフォーム別の手順を含む完全なインストールガイド：costwise-mcp.vercel.app/docs/install

クイックインストール（Linux／macOS／WSL 経由の Windows）

推奨方法は、次のコマンドを 1 つ実行するだけです。

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

スクリプトがすべて自動で行います。

1. Windows では Git Bash／MSYS を検出し、自動的に WSL 経由で実行します
2. Go を確認し、インストールされていない場合はインストールします
3. C コンパイラー（CGO の依存関係）を確認し、インストールされていない場合はインストールします
4. リポジトリをクローンし、ソースからビルドします
5. /usr/local/bin/costwise にインストールします
6. AI コーディングクライアントを検出し、接続するクライアントを確認します
7. 選択したクライアント向けに MCP を設定します（--no-skill を指定しない場合はセッションスキルもインストールします）

Windows（ネイティブ PowerShell）

すでに Go と gcc をお持ちの場合を除き、推奨しません。手動でビルドしてください。

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
$env:CGO_ENABLED=1
go build -o costwise.exe ./cmd/costwise/

または、推奨方法である WSL をインストールしてください（Windows 10 2004 以降／Windows 11）。

# In PowerShell as Administrator:
wsl --install

# Then in WSL:
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash

macOS／Linux（手動ビルド）

Go 1.25 以降と C コンパイラーが必要です（CGO は必須です。以下のビルドに関する注意事項を参照してください）。

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build -o costwise ./cmd/costwise/
sudo mv costwise /usr/local/bin/
costwise --version

スキーマと使用例を含むインタラクティブなツール一覧：costwise-mcp.vercel.app/tools

検索ツール

search_code

ネイティブの Bluge 逆引きインデックスと Tree-sitter を利用した、リポジトリのセマンティック検索です。

理由：「キャッシュはどこに実装されていますか？」という自然言語の質問には、モデルがファイルを 1 つずつ開くためのファイル一覧ではなく、関連するスコープを直接返すべきです。新しい Bluge インデックスは、AI による処理負荷なしで、高速な BM25／TF-IDF スコアリング、あいまい一致、同義語の展開をネイティブに提供します。

例：Where is caching implemented?

find_symbol

シンボルの定義箇所を検索します。

理由：「X はどこで定義されていますか？」は、最もよくあるナビゲーションの質問です。必要なのはファイルではなく、定義箇所です。

例：Find UserService

read_symbol

名前を指定して、シンボルの実装全体を返します。

理由：「X の仕組みを見せてください」という依頼には、ファイル全体のダンプや、エージェントが検索を繰り返して実装を再構築するのではなく、インデックスから行範囲を 1 回読み取って回答するべきです。

例：Show the body of GetOrCreateRepoSession

find_references

シンボルのすべての使用箇所を検索します。

*理由：*影響分析（「この変更で何が壊れますか？」）には、ツリー全体をその場で grep せず、事前計算されたすべての使用箇所が必要です。CostWise は、標準の LSIF（dump.lsif）の取り込みに対応し、コンパイラーで検証された参照を 100％ の精度で提供します。LSIF が利用できない場合は、Tree-Sitter による正規表現の近似検索に適切にフォールバックします。

例：Where is UserService used?

find_callers

別の関数を呼び出す関数を検索します。

*理由：*呼び出しチェーンを理解するには、呼び出し元のファイルを読んでモデルが再構築するのではなく、保存済みの呼び出しエッジを読み取るべきです。

例：What calls processPayment()?

注：search_code はすでに完全一致／全文検索の戦略を内部で使い分けているため、リテラル一致に別のツールは必要ありません。ファイルに対する生の正規表現検索には、ホストのネイティブなファイル検索を使用してください。

メンテナンスツール

get_repository_summary

リポジトリの概要をトークン予算内で表示します。言語、シンボル数の多い上位モジュール、主要なシンボルを確認できます。特定のディレクトリを詳しく調べるには module を、出力を制限するには budget（small／medium／large）を指定します。

理由： 通常、これはセッションで最初に呼び出されるため、キャッシュされたコンテキストに最初に取り込まれ、その後も保持される情報でもあります。以前のバージョンでは、ディレクトリごとに1行と、各ディレクトリの詳細な階層全体を制限なしで出力していました。大規模なモノレポでは数万トークンに達し、セッション全体でキャッシュされていました。現在は出力に厳しい上限を設けているため、リポジトリの規模にかかわらず出力は小さく保たれ、詳細は module で必要に応じて取得できます。

index_repository

リポジトリのインデックスを手動で更新または再構築します。通常、ウォッチドッグが自動でインデックスを再作成するため、必要ありません。

コンテキスト制御ツール（V2）

上記のキャッシュコストを抑えるためのツールです。大きなコンテンツや長期間保持する情報を、損失なく常駐ウィンドウの外に置けます。

remember

決定事項、エントリーポイント、注意点など、少量の長期間保持する情報をリポジトリごとのストアに保存します。関連するたびに会話内で繰り返す必要がなくなります。

理由： モデルがターンごとに再導出したり再貼り付けしたりする情報は、純粋なキャッシュのオーバーヘッドです。一度書き留め、必要なときに読み戻してください。

stash_context

ファイル全体、長いコマンドやテスト出力、生成されたレポートなど、大きなデータを会話の外に退避し、短いハンドルを取得します。データが失われることはありません。内容全体がディスクに書き込まれ、後から再取得できます。

理由： これはウィンドウサイズを抑える最も直接的な方法です。5,000行のログを会話に貼り付けると、セッション中の各ターンで再読され、キャッシュに再書き込みされる可能性があります。退避すれば、コストは約20トークン（ハンドル）で、必要な部分だけを取得できます。

例：5,000行のログを退避し、コンテキスト内には約20トークンだけを保持します。

recall

必要な分だけ取り出します。ハンドルで指定した保存済みデータの予算内の一部、または条件に一致する記憶済みの事実を取得します。全体を読み直す必要はありません。

理由：「必要なクエリで出力を取得する」ことが、このループの読み取り側です。stash_context と組み合わせると、巨大なデータを保存してから、トークン予算内でクエリに一致する行だけを recall できます。

ループ： stash_context（保存する）→ recall（必要な部分だけ取り出す）→ remember（長期的に役立つ結論を保持する）。内容はいつでも復元でき、コンテキストウィンドウは小さく保てます。

最初のコマンドから最終回答まで、一般的なセッションの流れと、コンテキストウィンドウに取り込まれずに済むトークン数を確認しましょう。

ステップ 1 — インストールとインデックス作成

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costwise-mcp/main/install.sh | bash
# Script detects OS, installs Go + C compiler if needed,
# builds binary, detects AI coding clients, and writes MCP config.
# The server auto-indexes your repo on first connection.

ステップ 2 — コーディングセッションを開始する

AI エージェントが MCP 経由で CostWise に接続します。接続すると、エージェントは約 275 トークンのセッションスキルを受け取り、インラインで貼り付ける代わりに stash／recall／remember を使う方法を把握します。

ステップ 3 — ナビゲーションに関する質問をする

ファイル全体を出力する代わりに、エージェントは次を呼び出します。

find_symbol("UserService")
→ user_service.go:142

read_symbol("UserService")
→ func (s *UserService) Create(ctx context.Context, req *CreateRequest) (*User, error) {
      // full body returned, not the whole file
  }

コスト：約 50 トークンです。CostWise がない場合、エージェントは user_service.go（500 行以上になる可能性があります）をコンテキストウィンドウに読み込みます。

ステップ 4 — 影響範囲を追跡する

「validateInput を呼び出しているのはどれですか？」と尋ねると、エージェントは次を呼び出します。

find_callers("validateInput")
→ processPayment (payment.go:310)
  → validateOrder (order.go:88)
    → validateInput (validator.go:45)

コスト：約 30 トークンです。CostWise がない場合、エージェントは各ファイルを開き、呼び出し元を読み、呼び出しの連鎖を再構築します。数百トークンがコンテキストウィンドウに入ります。

ステップ 5 — テストを実行して失敗を確認する

テストが失敗し、2,000 行のログが出力されます。全体をインラインで貼り付ける代わりに、次を実行します。

stash_context(label="test-failure-output", content=<full 2000-line log>)
→ Stashed → abc123 (~28,000 tokens kept out of context)

ハンドルのコストはコンテキスト内で約 20 トークンです。ログ全体はディスク上に保存されます。

ステップ 6 — 失敗を調査する

recall(source="abc123", query="FAIL|panic|error")
→ test_service_test.go:42: TestCreateUser FAILED
    expected: 201, got: 500
    error: database connection refused

コスト：約 40 トークン（一致した行のみ）です。CostWise がない場合、エージェントは 2,000 行のログ全体を再読込するか、再度貼り付けます。

ステップ 7 — 見つけたことを記憶する

remember(key="db-conn-fix", fact="Database connection refused in tests — check DB_HOST env var in .env.test")
→ Remembered "db-conn-fix"

コストは約 20 トークンで、セッションの残りの期間と今後のセッションにわたって保持されます。

ステップ 8 — 後で事実を呼び出す

recall(query="db fix")
→ db-conn-fix: Database connection refused in tests — check DB_HOST env var in .env.test

修正方法を再導出する必要はありません。コストは約 15 トークンです。

まとめ

セッション全体では、これらの節約が積み重なり、常駐コンテキストウィンドウ内のトークンを 80% 以上削減できます。さらに、その後の各ターンでキャッシュ読み取りのコストも減少します。

サイズの異なるリポジトリで、CostWise サーバーの「正直で生の」トークンフットプリントをテストします。

小規模リポジトリ（約 50 ファイル）

• リポジトリ全体を単純に読み込む場合のコンテキストコスト：約 12,500 トークン
• get_repository_summary (small)：286 トークン（0.01s）
• search_code (exact match)：4 トークン（0.31s）
• read_symbol：24 トークン（0.01s）
• 単純な読み込みと比較した平均トークン節約率：99.16%

中規模リポジトリ（約 250 ファイル）

• リポジトリ全体を単純に読み込む場合のコンテキストコスト：約 62,500 トークン
• get_repository_summary (small)：528 トークン（0.04s）
• search_code (exact match)：4 トークン（0.60s）
• read_symbol：24 トークン（0.03s）
• 単純な読み込みと比較した平均トークン節約率：99.70%

大規模リポジトリ（約 1000 ファイル）

• リポジトリ全体を単純に読み込む場合のコンテキストコスト：約 250,000 トークン
• get_repository_summary (small)：517 トークン（0.18s）
• search_code (exact match)：4 トークン（4.38s）
• read_symbol：24 トークン（0.37s）
• 単純な読み込みと比較した平均トークン節約率：99.93%

最適なケース： コンテキストの上限（例：200k トークン）により、ファイル全体をそのまま読み込むことが不可能、または非常にコストがかかる、大規模なコードベース（500 ファイル超）です。CostWise は、リポジトリのサイズにかかわらず、構造の理解を 500 トークン未満に圧縮します。

適さないケース： 小さなスクリプトや 1〜3 ファイルのプロジェクトです。コードベース全体が 2,000 トークン以内に余裕で収まる場合、Tree-Sitter によるインデックス作成や SQLite データベースの作成にかかるオーバーヘッドはまったく不要です。その場合は、ファイルを直接読んでください。

導入の理由： 上記のコンテキスト制御ツールは、モデルが実際に使わなければ役に立ちません。デフォルトのままでは、モデルはファイル全体をそのまま貼り付けてしまいます。costwise-session スキルは、セッションごとに一度だけ、無駄のないワークフローをモデルに教える小さなセッション認識ガイダンスです。その後は自動的に適用され、大きな出力は stash_context / recall を通して扱い、長期保存する事実は remember で保存し、ファイル全体を読むよりも対象を絞った取得を優先します。

意図的に非常に小さく（約 275 トークン）作られています。これはセッションごとに一度だけ発生する固定コストであり、大きなデータの塊がコンテキストウィンドウに入るのを一度でも防げば、十分に元が取れます。

継続的な手間をかけず、どこでも使えるよう、次の 2 つの方法で提供されます。

1. すべてのエディターで自動的に適用されます。 MCP サーバーは、プロトコルの instructions フィールドを通してガイダンスを通知します。接続時にすべての MCP クライアントが読み込みます。Claude Code、Cursor、Codex、OpenCode、Antigravity など、MCP 互換のクライアントすべてが対象です。設定は不要で、エディターごとのファイルも必要ありません。

2. ネイティブの Claude Code スキルとして利用できます。 costwise install を実行すると、~/.claude/skills/costwise-session/SKILL.md も書き込まれます（--no-skill で無効にできます）。直接管理することもできます。

   costwise skill install      # write the skill (global)
   costwise skill install --local   # write it into the current project only
   costwise skill uninstall    # remove it
   costwise skill print        # print the guidance for manual placement in any tool
   

独自のルールファイルや指示ファイルを読み込むエディター向けには、costwise skill print を実行すると、貼り付け用のガイダンスが出力されます。どちらの提供方法も、同じ単一の信頼できる情報源を使用します。

コンポーネントの詳細を掘り下げられるインタラクティブなアーキテクチャ図：costwise-mcp.vercel.app/architecture

エンタープライズ対応機能：

• コールドスタート時のレイテンシーゼロ： GitHub Action（costwise-action）と連携して、CI/CD 上で SQLite の cache.db を事前計算します。ローカルで起動すると、CostWise は事前計算されたアーティファクトを即座にダウンロードします。
• チームで共有するキャッシュ： COSTWISE_PG_URL を設定して、ローカルの SQLite の代わりに Postgres バックエンドに接続します。開発者 A が一時保存した内容や記憶させた事実を、開発者 B もすぐに利用できます。
• ポリシーエンジン： 一元管理された costwise-architecture.yaml 設定に対して、costwise validate による AST ベースの厳格なアーキテクチャ境界チェックを実施します。

AI Client (MCP Host)
    │
    ├── stdio transport ──► costwise serve (MCP Server)
    │                           │   advertises session guidance via the MCP instructions field
    │                           │
    │                           ├── Session Manager (per-repo, persistent across tool calls)
    │                           ├── Repository State Manager
    │                           ├── Watchdog
    │                           ├── Shared Indexer
    │                           │
    │                           ├── Tree-sitter Parser
    │                           ├── Symbol Index
    │                           ├── Reference Index
    │                           ├── Call Graph Index
    │                           │
    │                           ├── search_code ───────────► tree-sitter AST match
    │                           ├── find_symbol ───────────► SymbolDB lookup
    │                           ├── read_symbol ───────────► SymbolDB body read
    │                           ├── find_references ───────► SymbolDB reference search
    │                           ├── find_callers ──────────► SymbolDB call graph
    │                           ├── get_repository_summary ► KnowledgeStore (token-budgeted)
    │                           ├── index_repository ──────► SharedIndexer
    │                           ├── remember ──────────────► per-repo durable facts
    │                           ├── stash_context ─────────► large blobs parked out of context
    │                           └── recall ────────────────► query-scoped read-back

リポジトリごとの状態（インデックス、一時保存データ、事実）はすべて、そのリポジトリのローカルインデックスディレクトリに保存されるため、別々のリポジトリが互いのデータを上書きすることはありません。

1. MCP クライアントの設定を削除します（これによりセッションスキルも削除されます）。

costwise uninstall --all

2. バイナリを削除します。

Linux / macOS:

rm -f "$(command -v costwise)"

Windows:

Remove-Item (Get-Command costwise).Source -Force

CostWise のデータはすべて 2 か所に保存されます。必要に応じて、場所の確認や削除を行ってください。

リポジトリごとの保存場所（.mycli-fts/）

インデックス化された各リポジトリのルートに作成されます。そのリポジトリ固有のデータがすべて格納されます。

リポジトリのすべてのデータを消去するには、次を実行します。

rm -rf /path/to/your/repo/.mycli-fts

インデックスは次のセッションで自動的に再構築されます。

グローバルな保存場所（/tmp/）

すべてのリポジトリで共有されます。既知の落とし穴です。リポジトリごとに分離されていないため、互いに上書きする可能性があります。

rm -f /tmp/repo_memory.db /tmp/discovery_memory.db

バグ修正、新しい言語パーサー、より優れたリトリーバー、ドキュメント、ベンチマークなど、あらゆる貢献を歓迎します。

詳細はCONTRIBUTING.mdをご覧ください。

貢献者向けの主要ドキュメント：

• 信頼度と精度のスコアリング — 各検索ツールがスコアを付け、順位付けし、信頼度のしきい値を適用する方法を網羅した完全なガイドです。FTS、Tree-sitter、Grep、Reference、Call Graph、Architecture、Flow Graph、および Query/Answer Type 分類器の正確な数式、信頼度の上限、品質ゲート、判断ロジックを記載しています。

クイックスタート：

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build ./...
CGO_ENABLED=1 go test ./...

取り組みやすい課題：

• 新しい言語用の Tree-sitter 文法を追加する
• 共有されている /tmp/ DB パスの上書き問題を修正する（リポジトリごとのパスが必要です）
• 特定の回答タイプの圧縮を改善する
• リモートデプロイ用の SSE/HTTP トランスポートを追加する
• より優れたベンチマークを作成する

何から始めればよいかわからない場合は、ガイダンスを求める課題を作成してください。

git clone https://github.com/okyashgajjar/costwise-mcp.git
cd costwise-mcp
CGO_ENABLED=1 go build ./...
CGO_ENABLED=1 go test ./...

Ubuntu/Debian の場合：sudo apt install gcc libsqlite3-dev。macOS の場合：Xcode Command Line Tools。Windows の場合：MinGW-w64。

存在する理由： モデルは、クエリ対象のインデックスが信頼できるかどうかを把握する必要があります。CostWise は 3 つの状態を追跡し、それに応じて動作します。

エージェントモードでは必要に応じて自動でインデックスを作成できます。対話モードでは、最初に確認を求めます。

詳細なユースケースの事例をご覧ください：costwise-mcp.vercel.app/use-cases

• AI コーディングエージェント — スコープ単位の圧縮された検索でトークン消費を抑え、大きなコンテンツをコンテキスト外に退避させることで、長時間のセッションも低コストに保ちます。
• 大規模なモノレポ — ディスクをスキャンする代わりに、SQLite インデックスをマイクロ秒単位で高速にクエリできます。また、リポジトリのサイズにかかわらず小さく保たれる、予算に応じた要約を利用できます。
• コードレビュー — 呼び出し元の階層をたどり、変更が及ぼす影響を監査します。
• リポジトリ監査 — ファイルの分布、言語の内訳、構造の要約を生成します。
• MCP 開発 — stdio プロトコル、fsnotify ウォッチャー、tree-sitter マッピング、MCP instructions フィールドのリファレンス実装です。

costwise doctor で次の項目を確認できます。

• バイナリの存在と権限
• PATH からの参照可否
• 各クライアントの MCP 設定
• サーバーの起動
• リポジトリの状態

まだ解決しない場合は、costwise doctor を実行し、その出力を添えて issue を作成してください。

Go 1.25 以降と C コンパイラーを備えたすべてのプラットフォームに対応しています。インストールスクリプト（install.sh）がツールチェーンのセットアップを自動的に行います。

• Linux amd64 / arm64
• macOS amd64 / arm64（Intel および Apple Silicon）
• Windows amd64

Linux amd64 および Windows amd64 向けのビルド済みリリースバイナリを利用できます。それ以外のプラットフォームは、インストールスクリプトによってソースからビルドされます。