Skip to main content
Glama

Mason – LLM을 위한 컨텍스트 빌더 👷

npm version CI npm downloads license issues

Mason은 LLM에게 코드베이스의 영구적인 맵을 제공하여 매 세션마다 처음부터 탐색하지 않도록 합니다.

문제점: LLM이 코드에 대해 새로운 대화를 시작할 때마다 grep을 수행하고, 파일을 읽고, 아키텍처를 조합합니다. 이는 어제 이미 이해했던 컨텍스트에 대해 토큰을 낭비하는 것입니다. 164개의 파일로 구성된 프로젝트에서 "이 앱은 어떤 기능을 가지고 있는가?"라는 질문에 답하려면 여러 도구 호출을 통해 8개 이상의 파일을 읽어야 합니다.

Mason의 해결책: 세션 간에 유지되는 개념 맵입니다. 하나의 도구 호출로 기능-파일 조회 테이블을 반환하므로, 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은 영향을 받을 수 있는 다른 부분을 알려줄 수 있습니다. 수동으로 여러 도구를 호출해야 얻을 수 있는 세 가지 신호를 결합합니다:

  • 공동 변경 기록(Co-change history) — git 커밋에서 역사적으로 함께 변경된 파일들

  • 참조(References) — 대상을 이름으로 가져오거나 언급하는 파일들

  • 관련 테스트(Related tests) — 명명 규칙에 따라 대상과 쌍을 이루는 테스트 파일들

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은 MCP 클라이언트 없이 CLAUDE.md 파일을 생성하고 분석을 실행하기 위한 독립형 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