Skip to main content
Glama

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

npm version CI 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

Available Tools

12 tools
get_contextA

Assemble task context: matching decisions with rationale, approval, owner, sources, last review, and freshness, plus related tests, file impact, and any available map entries. Map verification is rechecked against sampled source contents; stale or unknown verification requires a fresh review, and recordedVerdict preserves the historical verdict. Proposals are suggestions; legacy records are unreviewed; accepted decisions are constraints subject to freshness. No initialization or map required. Pass task and optional files. map.status and diagnostics preserve missing or invalid knowledge. Impact covers up to three unique files, expanding directory anchors.

Inputs: dir (required), task (required), files.

get_impactA

Trace historical co-change partners, related tests, and references with evidence: resolved imports, explicit paths, or uncertain name candidates. Candidates are not proven dependencies. Deterministic and read-only; no initialization or concept map required.

Inputs: dir (required), files (required).

get_snapshotA

Return the optional feature-to-file architecture map with drift and trust evidence. Map verification is rechecked against sampled source contents; stale or unknown verification requires a fresh review, and recordedVerdict preserves the historical verdict. If no map exists, returns exists:false and points to decision context. Decision capture, get_context, and get_impact still work. No initialization required.

Inputs: dir (required).

mason_automationB

Inspect installed automation, observed host events, pending decision records and the notification baseline, or check all retained documentation findings across sessions. status is read-only; check saves local baselines and verification reports without editing source, approving advisories or consuming pending completion notices. Returns concise results with a full report path. Works without a map.

Inputs: dir (required), action (required).

mason_check_driftA

Check how far the concept map has drifted from HEAD. Deterministic (git + filesystem, no LLM). Returns which features/flows are stale and the changed files behind them, new source files not yet mapped, ghost files (mapped but deleted), renames, and a recommendation: up-to-date (nothing to do), incremental (update just the stale entries via save_snapshot), or full-rebuild (broad source review required). Call this before trusting the map in a long session, or when maintaining an existing map.

Inputs: dir (required).

mason_complete_initA

Record assistant instruction setup locally in ignored .mason/local/project.json, with feature settings in shared .mason/config.json. Other tools work without this marker. Repeated calls preserve the original setup time and existing settings.

Inputs: dir (required).

mason_initA

Inspect this project now: returns documentation audit findings, committed-diff review findings, decision/map status, and a quickstart playbook. Quickstart is read-only and deterministic. Explicit mode: setup validates shared configuration and activates locally without editing shared files; mode: init explicitly prepares MCP, instructions and lifecycle hooks for review and commit. Neither runs audits or prepares repairs; use only when requested. Optional host selects codex or claude. Optional base selects the review comparison; evidence imports CI manifests with check outcomes, commit freshness, and links to changed files and accepted decisions. Repeat calls refresh findings even after setup.

Inputs: dir (required), base, host, mode, +2 more.

review_decisionA

Prepare a decision review: returns the claim and any operative accepted revision, provenance, the latest inspection and history event (notes shortened), changed files with hunk and line counts and anchor commits since the latest valid inspection for both sets of anchors, and a reviewToken. Request the diff (optionally for specific diffFiles), source previews or full history with include; the token is unchanged. For accepted-guidance inspection use inspectionScope operative on both prepare and inspect; pending proposals remain unassessed. Default all scope covers both revisions. After source inspection, record inspect with inspector, note and token to report no contradiction found without human acceptance. For human review, prepare with all scope, then record accept, reaffirm, or retire with its token, the authorized reviewer, and a reason. Acceptance replaces the operative revision; retirement withdraws the entire record including its proposal. Acceptance requires owner, source, readable Git HEAD, and committed anchor changes. Changed records or code invalidate the token. Identities and approvals are recorded assertions for normal PR review, not authenticated proof.

Inputs: id (required), dir (required), note, action, +7 more.

save_decisionA

Capture or revise a decision proposal as soon as the lesson is supported by evidence, without waiting for implementation or merge. Keep unimplemented remedies tentative. Include rationale, anchors, optional owner, sources, and a known actor. Compare matching get_context records and pending proposals before saving. When new evidence changes the same lesson's assumptions, scope, or recommended action, pass its existing id, including for accepted records. Preserve supported rationale and sources and replace obsolete instructions. Create a new record for a genuinely distinct lesson; skip unchanged restatements. No setup or map required. Writes a local record and preserves content history. Changes create a pending proposal while the last accepted revision remains operative; unchanged content does not re-verify or refresh it. Use review_decision for authorized acceptance or reaffirmation. A proposal cannot supersede a record with an operative accepted revision; review its replacement and retire the original separately.

Inputs: dir (required), body (required), title (required), category (required), +7 more.

save_snapshotA

Save a concept-to-files map as a persistent project snapshot. Maps feature names and data flows to the files that implement them. Retained for direct maintenance of legacy maps; the managed map-build workflow has been removed. Persists across conversations — future sessions can call get_snapshot to instantly find relevant files. No API key needed — you are the LLM generating the map.

Inputs: dir (required), flows (required), features (required), removeFlows, +1 more.

save_verificationA

Record verify_snapshot verdicts using each entry’s kind and reviewToken. Missing tokens request a fresh review; changed or deleted entries return conflicts without being stamped. Entries judged ok are stamped verifiedAt; failures are flagged verificationFailed with your note and surface in get_context, get_snapshot, and mason_check_drift until corrected. Verdict notes are required for failures.

Inputs: dir (required), verdicts (required).

verify_snapshotA

Spot-check the concept map's CORRECTNESS (drift checks freshness; this checks entries were right to begin with). Returns a sample of entries — always the never-verified and least-recently-verified first — with skeletons of their claimed files, for you to judge whether the files actually implement what the entry claims. Report verdicts back via save_verification with each entry’s kind and reviewToken. Tokens bind the entry and bounded source evidence; changed evidence requires a fresh review. Run periodically, or after an automated refresh wrote entries no human reviewed.

Inputs: dir (required), sample.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation3/5

    Several clusters overlap: mason_init, mason_complete_init, and mason_automation all touch setup/inspection state, while get_snapshot, get_context, get_impact, and verify_snapshot all return map/context views that an agent could easily conflate. verify_snapshot with save_verification and check_drift form a defensible pairing, and the save/review decision tools are distinct, but the descriptions' dense terminology makes tool selection error-prone.

    Naming Consistency3/5

    Most names follow a verb_noun pattern (get_snapshot, save_decision, review_decision, check_drift), but only some carry the mason_ prefix (mason_check_drift, mason_init, mason_automation, mason_complete_init) while others do not. 'mason_complete_init' also breaks the verb_noun reading and is easily confused with mason_init.

    Tool Count4/5

    Twelve tools is within a reasonable band for a map plus decision-lifecycle server, and each cluster (drift, verification, decisions, setup) earns roughly its place. The setup triplet of mason_init, mason_complete_init, and mason_automation is the one area where consolidation would help.

    Completeness4/5

    The surface covers the full knowledge lifecycle: map save/get, drift checking, verification verdicts, decision save/review/accept/retire, context assembly, and impact analysis. Minor gaps exist — no tool to delete or clear a snapshot map, and no way to enumerate decisions beyond task-matched get_context lookups.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A TypeScript tool that ranks files in your codebase by importance, tracks dependencies, and provides file summaries to help understand code structure through Cursor's Model Context Protocol.
      14
      302
      -
    • A
      license
      A
      quality
      D
      maintenance
      Extract domain knowledge from codebases to reduce LLM token consumption by 20x and time in agentic search by 10x — gathers and makes concepts, naming conventions, and vocabulary queryable via MCP.
      19
      44
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Turns local code repositories into a queryable dependency graph built from AST parsing and git co-edit history, then exposes it alongside an Obsidian vault as persistent memory. Enables context retrieval, impact analysis of proposed changes, and curation of durable prose knowledge through full-text search and Personalized PageRank classification—all fully offline without API keys or embeddings.
      30
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Turns a codebase into a persistent knowledge graph so AI coding agents can answer structural questions about functions, call chains, routes, and cross-service links through graph queries instead of reading files one by one.
      MIT