Mason – LLMのためのコンテキストビルダー 👷

npm version npm downloads license issues

Masonは、LLMにコードベースの永続的なマップを提供し、セッションごとにゼロから探索し直す必要をなくします。

課題: LLMがコードについて新しい会話を始めるたびに、grepを実行し、ファイルを読み込み、アーキテクチャを再構築します。これは、昨日すでに理解していたコンテキストに対してトークンを浪費していることになります。164ファイルあるプロジェクトで「このアプリにはどんな機能があるか」という問いに答えるには、複数のツール呼び出しをまたいで8つ以上のファイルを読み込む必要があります。

Masonの解決策: セッションをまたいで永続化されるコンセプトマップです。1回のツール呼び出しで機能とファイルの対応表が返されるため、LLMは探索することなく、どこを見るべきかを正確に把握できます。

測定結果 (deepeval、Claude Sonnet、164ファイルのKMPプロジェクト):

質問	Masonあり	Masonなし	トークン削減率
全機能のリストアップ	10,258 tok	31,346 tok	67%
データフローの追跡	12,010 tok	15,258 tok	21%
プラットフォームの比較	10,897 tok	19,353 tok	44%
オンボーディングフロー	10,271 tok	11,432 tok	10%
平均			36%

回答の品質は同等（両方のパスで全テストにおいて0.9/1.0）。再現方法: bench/。

クイックスタート

claude mcp add mason --scope user -- npx -p mason-context mason-mcp

Claude Codeを再起動し、次のように尋ねてください: "use mason to analyze this project and create a snapshot."

これだけです。Masonがコードベースを分析し、コンセプトマップを作成します。次回のセッションでは、すべてを再探索する代わりにこのマップを読み込みます。

Related MCP server: ontomics

仕組み

コンセプトマップ

Masonの核となる機能です。機能とファイルのマップを .mason/snapshot.json に永続化し、会話をまたいで保持します。LLMがプロジェクトを理解する必要があるとき、コードベース全体をgrepする代わりにこのマップを読み込みます:

{
  "features": {
    "home screen": {
      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
    }
  },
  "flows": {
    "weather fetch": {
      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
    }
  }
}

マップはLLM自身によって生成されます。Masonは分析ツールを提供し、LLMがコードを解釈して機能やフローが何であるかを決定します。つまり、マップは単なるファイルリストではなく、アーキテクチャの理解を捉えたものになります。

AIアシスタントに "create a mason snapshot" と尋ねるか、CLI経由で作成してください:

mason set-llm gemini          # configure a provider (no API key needed)
mason snapshot ~/my-project   # generate concept map
mason snapshot --install-hook # auto-update on every commit

変更の影響分析

ファイルを編集する前に、Masonは他にどのような影響が出る可能性があるかを教えてくれます。手動で行うと複数のツール呼び出しが必要になる3つのシグナルを組み合わせます:

同時変更履歴 — Gitコミットで歴史的に一緒に変更されるファイル
参照 — ターゲットをインポートしている、または名前で言及しているファイル
関連テスト — 命名規則によってターゲットとペアになっているテストファイル

mason impact WeatherRepository.kt -d ~/my-project

get_impact MCPツールとしても利用可能です。アシスタントに "what would be affected if I changed WeatherRepository?" と尋ねてください。

Git履歴分析

Masonは何百ものコミットを集約して実用的な統計を出します。最も頻繁に変更されるファイル（注意が必要なホットファイル）、数ヶ月間触れられていないディレクトリ（潜在的に古いコード）、チームが従っているコミット規則などです。これらは手動で計算しようとすると数十回の git log 呼び出しが必要になるような分析です。

mason analyze ~/my-project

MCPツール

MasonはModel Context Protocolを通じて6つのツールを公開しています。MCP互換クライアント（Claude Code、Cursorなど）であればどれでも使用可能です:

ツール	機能
`get_snapshot`	コンセプトマップの読み込み — 機能/フローとファイルの対応
`save_snapshot`	将来のセッションのためにコンセプトマップを永続化
`get_impact`	変更の影響分析: 同時変更履歴、参照、関連テスト
`analyze_project`	Git履歴: コミットパターン、ホットファイル、古いディレクトリ
`full_analysis`	初回訪問用オールインワン: Git統計 + 構造 + コードサンプル + テストマップ
`get_code_samples`	アーキテクチャ上の役割によって選択されたスマートなファイルプレビュー

CLIの使用方法

Masonは、CLAUDE.mdファイルの生成やMCPクライアントなしでの分析実行を行うためのスタンドアロンCLIとしても機能します。LLMプロバイダーを一度設定すれば、どのコマンドでも使用できます:

mason set-llm claude|gemini|ollama|openai  # configure provider
mason generate                # analyze codebase + LLM -> CLAUDE.md
mason analyze                 # git stats only (no LLM needed)
mason impact File.kt          # change impact analysis
mason snapshot                # create/update concept map

ほとんどのプロバイダーはAPIキーなしで動作します。claude、gemini、ollama はすべてそれぞれのCLIを直接使用します。

セキュリティ

スナップショットに含まれるもの: 機能名、相対ファイルパス、フローの説明。ソースコード、秘密情報、ビジネスロジックは含まれません。

触れないもの: Masonは .gitignore を尊重し（git ls-files 経由）、.env、.pem、.key、認証情報、その他の機密ファイルをサンプリングから除外する拒否リストを持っています。パストラバーサル保護により、すべてのファイルアクセスがプロジェクトルート内に留まることが保証されます。

LLMのデータフロー: CLI経由でスナップショットを生成すると、サンプリングされたファイルの内容が設定したLLMプロバイダーに送信されます。これはAIコーディングアシスタントがコードを読み取るのと同じ方法です。完全にローカルで生成したい場合は ollama を使用してください。MCPサーバーツール（get_snapshot、get_impact など）はローカルファイルのみを読み取ります。

言語サポート

Masonは完全に言語に依存しません。言語固有の解析ではなく、ファイル命名パターンとGit履歴を使用するため、ソースファイルとGitリポジトリを持つあらゆるプロジェクト（TypeScript、Kotlin、Python、Go、Rust、Swift、Java、C#、Dartなど）で動作します。

ライセンス

MIT

mason