mason
Mason is an MCP server that helps AI agents prevent documentation/architecture drift, capture decisions, and manage project knowledge.
Quickstart audits: Run read-only README/instruction audits and committed-diff reviews, import CI evidence, and get findings plus a quickstart playbook.
Setup integration: Configure Codex or Claude with MCP, hooks, and project instructions (
mason_initsetup mode,mason_complete_init).Automation status/receipts: Inspect installed automation and observed host events, or resume/check retained documentation repair evidence across sessions.
Repair tracking: Prepare and verify documentation repair work orders against original audit evidence (
mason_repair).Advisory reviews: Assess original repair advisories and record addressed, inapplicable, or deferred outcomes with review tokens (
review_advisory).Decision management: Capture, retrieve, and review decisions/gotchas/deprecations/conventions with rationale, anchors, owners, sources, and freshness (
save_decision,get_context,review_decision).Architecture maps: Build or refresh feature-to-file concept maps via batch Map-Reduce (
generate_snapshot_batch,save_partial_snapshot,reduce_snapshot,save_snapshot).Map verification and drift: Check map freshness against HEAD (
mason_check_drift), spot-check entry correctness (verify_snapshot,save_verification).Codebase orientation: Get project structure, git history stats, code samples, test-to-source mapping, and impact/co-change analysis (
full_analysis,analyze_project,get_code_samples,get_impact).Confluence sync: Configure Confluence credentials and export product-readable feature pages, index, and changelog (
mason_set_confluence,export_to_confluence).
Provides tools for analyzing git history to identify hot files, stale directories, commit patterns, and co-change relationships for impact analysis.
Supports using Ollama as a local LLM provider for generating concept maps and analyzing codebases without sending data to external services.
Supports using OpenAI as an LLM provider for generating concept maps and analyzing codebases through the Mason CLI.
Mason
Preserve why your code was built this way.
Record the reason · Review the lesson · Surface applicable guidance · Reconsider it as code changes
Mason preserves reviewed engineering reasoning with your repository, so future maintainers and coding agents can retrieve the evidence behind consequential decisions. Record workarounds, rejected approaches and constraints while their reasons are available; revisit them when the underlying code changes.
Get started
Install on macOS or Linux:
curl -fsSL https://github.com/adrianczuczka/mason/releases/latest/download/install.sh | shWindows PowerShell:
irm https://github.com/adrianczuczka/mason/releases/latest/download/install.ps1 | iexNo Node or npm required. Git is required. The installer configures PATH for Bash, Zsh, and Windows. Platform details · npm installation
New standard standalone installs update automatically in the background. Updates activate on a future MCP launch after existing Mason MCP servers exit. Run mason updates to inspect or change this preference. Existing installations require one manual upgrade and mason updates enable. Update controls
Run this in your Git repository (open a new terminal if the installer asks):
mason init --host codex # Maintainer: prepare shared configuration for review/commit
mason setup --host codex # Each developer: activate locally
# For Claude Code, use --host claude.If the repository already has compatible Mason configuration, run only mason setup. Initialization prepares MCP, hooks and project instructions; setup leaves shared files untouched. Review your host's trust settings, start a new session, and give your agent a normal task.
Check that Mason is being used:
mason statusSetup uses your installed mason command—no project launch scripts or runtime copies. Status distinguishes configuration from observed use. Setup and upgrades · Disconnect a project · Other MCP clients
Try a check without setup
mason audit --dir .
mason review --dir . --base origin/mainThe audit checks claims in README and agent instruction files throughout the repository. The review checks committed changes against your chosen base. Both are read-only and need no model calls.
Related MCP server: ontomics
What Mason catches
As your project grows… | Mason helps by… |
Instructions fall behind the code. | Flagging missing paths, incorrect workspace counts, and missing npm scripts. |
A patch misses a related update. | Surfacing references, related tests, and files that historically change together. |
Old decisions lose their context. | Retrieving recorded rationale and review status, and flagging changes to the code they apply to. |
A repair gets interrupted. | Retaining the original findings and verifying them through the final documentation commit. |
After resolving an incident or settling a constraint, ask your agent to record a sourced proposal with Mason. Review it before accepting it as project guidance. Later tasks can retrieve the operative accepted revision while proposed replacements remain distinct, and changes to referenced code can prompt inspection, revision or retirement.
Mason complements tests, linters, and code review. Findings are evidence to inspect; unavailable checks stay explicit.
Evidence so far
Earlier read-only decision-retrieval evaluations scored 9.0/10 with Mason vs 7.0/10 without. The initial ten-task patch comparison tied at 10/10 for both. Improved patch outcomes remain to be demonstrated. Results, methodology, and limitations
Maintained notes also succeeded in the reuse trials. Recent hook experiments verified supported file delivery, with additional context cost and no demonstrated correctness gain; direct delivery for ordinary Bash workflows remains open. The current focus is useful preservation and reuse of engineering reasoning during ordinary work, with capture and maintenance effort that feels worthwhile. Preventing repeat mistakes is one intended benefit; comparative superiority remains unestablished. Positioning and validation plan · Current evidence
Documentation
Development
For development, use Node 20 (20.19+), Node 22 (22.13+), or Node 24+.
After npm ci, run npm run format to format TypeScript sources, tests, and tooling configs.
CI checks formatting with npm run format:check and runs npm run lint,
npm run typecheck, and the test suite. Run npm test locally to check behavior.
ESLint uses the recommended TypeScript rules plus type-aware checks for unhandled
promises, misused async callbacks, and invalid awaits. Prettier handles formatting.
Test fixtures and generated outputs are excluded from formatting and linting.
Production sources also reject explicit any and unsafe assignments, property
access, calls, arguments, and returns. External data is validated before use.
Test doubles keep the more permissive rules.
Available Tools
12 toolsget_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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Related MCP Servers
- FlicenseAqualityDmaintenanceA 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.14302-
- AlicenseAqualityDmaintenanceExtract 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.1943MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with persistent architectural memory of codebases, enabling impact analysis, test generation, and code generation with reduced token usage.MIT
- FlicenseBqualityBmaintenanceTurns 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-