F
licenseA
qualityD
maintenanceA 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
-
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| task | Yes | The task, bug, or change request in natural language — e.g. 'add rate limiting to the API client' or a ticket description | |
| files | No | Optional file paths already known to be involved (e.g. from a diff or stack trace). Entries containing them are boosted above pure text matches. |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so richly: it discloses rechecking of map verification, stale/unknown verification requiring fresh review, recordedVerdict preserving history, semantic distinctions for proposals/legacy/accepted records, and impact limits. These are genuinely useful behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause contributes meaning, and it is front-loaded with the core purpose before caveats. It is longer than the minimum, but the density is warranted given the behavioral nuances and absent annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description outlines what the assembled context contains and important constraints. It lacks an explicit return-value shape or explicit alternative routing, but for a 3-parameter tool with full schema coverage, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds only light value by mentioning 'task and optional files' and noting that impact covers up to three unique files, but it does not substantially extend the schema's already-complete parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Assemble task context') and names the precise resource: matching decisions with rationale, approval, owner, sources, freshness, tests, file impact, and map entries. This clearly distinguishes get_context from decision-writing, review, verification, and impact-only sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual conditions: 'No initialization or map required' and 'Pass task and optional files.' This tells an agent when this tool is appropriate without prerequisites. It does not explicitly name alternatives or exclusions, but the context is strong enough for intended use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| files | Yes | File paths or names to analyze (e.g., ['WeatherRepository.kt'] or ['src/services/auth.ts']) |
TDQS
A3.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: deterministic, read-only, no prerequisite setup, and an important caveat that candidates are not proven dependencies (epistemic status of results). It still omits performance characteristics and the shape of returned results, so it falls short of fully rich behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, correctly front-loaded with the purpose and then prerequisites and caveats. Every clause adds signal, though the colon-list of evidence types reads slightly stacked and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, required-only tool with no output schema and no annotations, the description supplies purpose, prerequisites, determinism, and a caveat about result reliability. It is close to complete, missing only any hint at result volume or how to interpret the evidence categories it mentions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (dir, files) are already documented with examples in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('trace') and concrete resources (historical co-change partners, related tests, references), and even names the evidence types returned. It is clearly distinguishable from snapshot/decision siblings, though it never explicitly contrasts itself with the closest neighbors like get_context or full_analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent a precondition ('no initialization or concept map required') and implies read-only analysis, but gives no explicit when-to-use-this-vs-alternatives guidance against get_context or full_analysis. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_snapshot
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory |
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project directory | |
| action | Yes | Inspect configuration and receipts, or capture/resume and verify original audit evidence. |
TDQS
B3.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does meaningful work: it declares status read-only and states that check saves baselines and reports 'without editing source, approving advisories or consuming pending completion notices' — valuable negative-side-effect disclosure. It also notes a return shape ('full report path'), though it omits permissions and idempotency details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The two sentences are front-loaded with the inspection targets and avoid obvious padding, but the second sentence piles several negated caveats together and the trailing 'Works without a map' is an unexplained fragment. Some jargon could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, two-mode tool with no output schema and no annotations, the description adequately covers modes, side-effect profile, and return hint. It is nevertheless thin on how each mode relates to the numerous sibling tools and leaves cryptic phrases undefined, so it is complete only at a minimum-viable level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented in the schema, setting the baseline at 3. The description adds a behavioral gloss on the two action values in prose, but no format or semantics beyond what the enum and dir descriptions already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states two specific verbs ('Inspect' for status, 'check' for the second mode) and enumerates resources (installed automation, host events, decision records, documentation findings). However, the resource list is dense domain jargon ('notification baseline', 'works without a map') and the tool bundles two distinct actions, so an outside agent gets only an approximate sense of purpose. No sibling tool is named or contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when each mode applies ('status is read-only' vs 'check saves local baselines and verification reports'), which gives an agent a rough basis for choosing an action. But no explicit alternatives are named (e.g., mason_check_drift, review_advisory) and no conditions for when NOT to use this tool are given, so routing against the many siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
mason_check_drift
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory |
mason_complete_init
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory |
mason_init
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| base | No | Quickstart only: Git ref for committed-diff review. Defaults to the first available main branch ref. | |
| host | No | Assistant to configure in init/setup mode; inferred only when unambiguous. | |
| mode | No | Quickstart inspects without edits; init prepares shared configuration; setup activates compatible configuration locally. | quickstart |
| dryRun | No | Init only: preview shared configuration changes without writing files. | |
| evidence | No | Quickstart only: repository-local CI evidence manifests to include in the review. Imports Vitest JSON, SARIF, and native-validator mason-check-json results without executing check commands. |
review_decision
Prepare a decision review: returns the full record and history, any operative accepted revision, provenance, changes and previews for both sets of anchors, and a reviewToken. 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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Decision id from get_context or save_decision | |
| dir | Yes | Absolute path to the project root directory | |
| note | No | Review rationale; required for a verdict. Cite evidence for the decision. | |
| action | No | Prepare is read-only. Inspect records an agent assessment without approval; accept, reaffirm and retire require an authorized review. | prepare |
| reviewer | No | Identity of the actual reviewer; required for a verdict. Never invent one. | |
| inspector | No | Actual agent or person performing inspection; required for inspect. Does not claim human approval. | |
| reviewToken | No | Token from the prepared review; rejects stale record or code revisions | |
| inspectionScope | No | For prepare/inspect only: all covers the full record and both anchor sets (default); operative covers only an active accepted revision, leaving a pending draft unassessed. Use the same scope when submitting its token. | all |
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Pass the matching record's existing id when evidence changes that lesson's assumptions, scope, or recommended action, including for accepted records. Changed content becomes a proposal while the accepted version remains operative; unchanged content leaves review and freshness untouched. | |
| dir | Yes | Absolute path to the project root directory | |
| body | Yes | The knowledge itself: what was tried/decided, why, and what to avoid. Must contain information NOT derivable by reading the code. Aim for 1500 characters or fewer; up to 2500 is accepted with a warning above the target. Matching context and hooks include the full body. Preserve exceptions; use sources for supporting references. | |
| actor | No | Known person or agent recording this revision. Omit if unknown; do not infer from Git identity. | |
| files | No | Repo-relative files or directory prefixes this applies to. Matching is shared by retrieval, hooks, review, and drift checking; changes flag the decision for re-verification. | |
| force | No | Save even when a near-duplicate was detected | |
| owner | No | Responsible person or team, when known. Null clears it. Required for acceptance. | |
| title | Yes | Short, specific headline (max 80 characters). Generates a stable id on creation; revising the title keeps the existing id. | |
| sources | No | Known PR, issue, incident, discussion, or document references. Omit to preserve; [] clears. At least one is required for acceptance. | |
| category | Yes | ||
| supersedes | No | Id of an unreviewed record or proposal with no accepted revision to replace. Operative accepted decisions require separate review and retirement. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and largely delivers: it discloses that it writes a local record, preserves content history, creates a pending proposal while the last accepted revision stays operative, does not re-verify unchanged content, and cannot supersede an operative accepted revision. It doesn't cover permissions/auth or rate/conflict handling in detail, but the lifecycle behavior is well documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and somewhat repetitive, revisiting the id/proposal/acceptance behavior multiple times and echoing the schema's id text. Front-loaded purpose is good, but several sentences could be consolidated without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with no annotations and no output schema, the description covers the essential lifecycle, idempotency, and cross-tool routing an agent needs. What is missing (authorization details, error/conflict outcomes) is minor relative to what is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 91%, so the schema already documents parameters such as id, owner, sources, files, and supersedes. The description restates id and sources semantics (preserve rationale/sources, replace obsolete instructions), adding modest value but little that the schema descriptions do not already convey. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Capture or revise a decision proposal') and immediately clarifies scope ('as soon as the lesson is supported by evidence, without waiting for implementation or merge'). It distinguishes itself from the sibling 'review_decision' and from 'get_context' records, so an agent can identify the tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use and when-not rules: compare matching get_context records and pending proposals before saving, pass the existing id when the same lesson changes, create a new record for a distinct lesson, skip unchanged restatements, and use review_decision for acceptance. Alternatives and conditions are named rather than inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
save_snapshot
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| flows | Yes | Map of flow names to ordered file chains | |
| features | Yes | Map of feature names to their implementing files | |
| removeFlows | No | Flow names to delete from the existing map. Applied before merging; only meaningful on incremental saves. | |
| removeFeatures | No | Feature names to delete from the existing map — for features that were renamed or no longer exist. Applied before merging; only meaningful on incremental saves. |
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| verdicts | Yes | Entry name → verdict, exactly as returned by verify_snapshot |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses side effects (stamped verifiedAt, flagged verificationFailed), persistence of failures across other tools (get_context, get_snapshot, mason_check_drift), and a hard requirement (note required for failures). It also explains the effect of missing tokens. This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph of four sentences, each adding distinct value: core action, edge cases, success/failure outcomes, and a requirement. It front-loads the primary purpose and avoids redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with two parameters and nested verdicts, the description fully covers what the tool does, when to use it, edge-case behavior, downstream visibility, and parameter requirements. Without an output schema, the description sufficiently informs the agent about what happens after invocation. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds behavioral context: it explains that kind and reviewToken are essential for recording, that missing tokens trigger fresh review, and that notes are required for failures. This goes beyond schema definitions and meaningfully aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Record verify_snapshot verdicts' and specifies the method (using each entry's kind and reviewToken). It also differentiates from siblings by naming verify_snapshot as the source and listing downstream tools that surface failures, making its unique role unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the primary use case (recording verdicts from verify_snapshot) and explains edge-case behavior (missing tokens request fresh review, conflicts for changed/deleted entries). It doesn't explicitly name alternative tools like save_decision, but the purpose is unambiguous and the conditions are clear, so only a minor gap exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Absolute path to the project root directory | |
| sample | No | Entries to sample (default 5) |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the sample ordering ('never-verified and least-recently-verified first'), that results include skeletons of claimed files, and that reviewTokens bind entries to bounded evidence and become stale when evidence changes. This gives an agent the key behavioral context needed to use the tool safely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: purpose and contrast first, then output shape, then workflow and cadence. Every clause earns its place, and there is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema or annotations, the description explains what is returned, why it is returned, and what to do next. It is complete enough for a two-parameter review tool; only explicit details about the exact response envelope or error behavior would make it fully exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents dir and sample, including the default for sample. The description adds little beyond the schema's parameter meanings, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Spot-check the concept map's CORRECTNESS' and clearly states what it returns. It also differentiates from drift checking ('drift checks freshness; this checks entries were right to begin with'), so an agent can distinguish it from similar sibling tools like mason_check_drift.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly contrasts this tool with drift checking and gives concrete guidance: 'Run periodically, or after an automated refresh wrote entries no human reviewed.' It also routes the follow-up action to save_verification, telling the agent exactly where to report verdicts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
14 tool updates
v0.22.0- Removed
analyze_project - Removed
export_to_confluence - Removed
full_analysis - Removed
generate_snapshot_batch - Removed
get_code_samples - Changed
mason_complete_init1 field changed- removed
Input schema / properties / confluenceConfiguredRemoved value: -{ - "description": "Set the Confluence setup status; omit to preserve the existing value", - "type": "boolean" -}
- Changed
mason_init6 fields changed- changed
Input schema / properties / base / descriptionPrevious value: -"Git ref for committed-diff review. Defaults to the first available main branch ref."New value: +"Quickstart only: Git ref for committed-diff review. Defaults to the first available main branch ref." - added
Input schema / properties / dryRunAdded value: +{ + "description": "Init only: preview shared configuration changes without writing files.", + "type": "boolean" +} - changed
Input schema / properties / evidence / descriptionPrevious value: -"Repository-local CI evidence manifests to include in the review. Imports Vitest JSON, SARIF, and native-validator mason-check-json results without executing check commands."New value: +"Quickstart only: repository-local CI evidence manifests to include in the review. Imports Vitest JSON, SARIF, and native-validator mason-check-json results without executing check commands." - changed
Input schema / properties / host / descriptionPrevious value: -"Assistant to configure in setup mode; inferred only when unambiguous."New value: +"Assistant to configure in init/setup mode; inferred only when unambiguous." - changed
Input schema / properties / mode / descriptionPrevious value: -"Quickstart inspects without edits; map requests an architecture build; setup installs the shared onboarding flow."New value: +"Quickstart inspects without edits; init prepares shared configuration; setup activates compatible configuration locally." - changed
Input schema / properties / mode / enumPrevious value: -[ - "quickstart", - "map", - "setup" -]New value: +[ + "quickstart", + "init", + "setup" +]
- Removed
mason_repair - Removed
mason_set_confluence - Removed
reduce_snapshot - Removed
review_advisory - Changed
review_decision4 fields changed- changed
Input schema / properties / action / descriptionPrevious value: -"Prepare is read-only. Other actions record an explicitly authorized review."New value: +"Prepare is read-only. Inspect records an agent assessment without approval; accept, reaffirm and retire require an authorized review." - changed
Input schema / properties / action / enumPrevious value: -[ - "prepare", - "accept", - "reaffirm", - "retire" -]New value: +[ + "prepare", + "inspect", + "accept", + "reaffirm", + "retire" +] - added
Input schema / properties / inspectionScopeAdded value: +{ + "default": "all", + "description": "For prepare/inspect only: all covers the full record and both anchor sets (default); operative covers only an active accepted revision, leaving a pending draft unassessed. Use the same scope when submitting its token.", + "enum": [ + "all", + "operative" + ], + "type": "string" +} - added
Input schema / properties / inspectorAdded value: +{ + "description": "Actual agent or person performing inspection; required for inspect. Does not claim human approval.", + "maxLength": 200, + "minLength": 1, + "type": "string" +}
- Removed
save_partial_snapshot - Changed
save_snapshot1 field changed- changed
Input schema / properties / features / additionalProperties / properties / type / descriptionPrevious value: -"Classification: \"capability\" for user-facing functionality, \"infrastructure\" for internal plumbing with no end user (DI/service wiring, config, logging, adapters). Capabilities are published to Confluence; infrastructure stays in the AI concept map only. Defaults to \"capability\"."New value: +"Classification: \"capability\" for user-facing functionality, \"infrastructure\" for internal plumbing with no end user (DI/service wiring, config, logging, adapters). Defaults to \"capability\"."
1 tool update
v0.19.1- Changed
review_advisory2 fields changed- changed
Input schema / properties / action / enumPrevious value: -[ - "prepare", - "addressed", - "inapplicable", - "deferred" -]New value: +[ + "prepare", + "addressed", + "inapplicable", + "deferred", + "dismiss" +] - added
Input schema / properties / reasonCodeAdded value: +{ + "enum": [ + "no-dependency-claims", + "unrelated-manifest-change" + ], + "type": "string" +}
1 tool update
v0.19.0- Changed
save_verification2 fields changed- added
Input schema / properties / verdicts / additionalProperties / properties / kindAdded value: +{ + "description": "Entry kind returned by verify_snapshot; required to record a verdict", + "enum": [ + "feature", + "flow" + ], + "type": "string" +} - added
Input schema / properties / verdicts / additionalProperties / properties / reviewTokenAdded value: +{ + "description": "Copy the reviewToken from verify_snapshot after inspecting its evidence; required to record a verdict", + "type": "string" +}
17 tool updates
v0.17.0- Added
export_to_confluence - Added
generate_snapshot_batch - Added
get_context - Added
mason_automation - Added
mason_check_drift - Added
mason_complete_init - Added
mason_init - Added
mason_repair - Added
mason_set_confluence - Added
reduce_snapshot - Added
review_advisory - Added
review_decision - Added
save_decision - Added
save_partial_snapshot - Changed
save_snapshot3 fields changed- added
Input schema / properties / features / additionalProperties / properties / typeAdded value: +{ + "description": "Classification: \"capability\" for user-facing functionality, \"infrastructure\" for internal plumbing with no end user (DI/service wiring, config, logging, adapters). Capabilities are published to Confluence; infrastructure stays in the AI concept map only. Defaults to \"capability\".", + "enum": [ + "capability", + "infrastructure" + ], + "type": "string" +} - added
Input schema / properties / removeFeaturesAdded value: +{ + "description": "Feature names to delete from the existing map — for features that were renamed or no longer exist. Applied before merging; only meaningful on incremental saves.", + "items": { + "type": "string" + }, + "type": "array" +} - added
Input schema / properties / removeFlowsAdded value: +{ + "description": "Flow names to delete from the existing map. Applied before merging; only meaningful on incremental saves.", + "items": { + "type": "string" + }, + "type": "array" +}
- Added
save_verification - Added
verify_snapshot
6 tool updates
v0.1.0- First observed
analyze_project - First observed
full_analysis - First observed
get_code_samples - First observed
get_impact - First observed
get_snapshot - First observed
save_snapshot
TDQS
A3.7/5.0
Scored across 22 tools
Disambiguation4/5
Tools are largely distinct: map building, decision lifecycle, advisory review, setup, and orientation each have dedicated operations. Minor ambiguity remains among orientation/read tools such as full_analysis, analyze_project, get_code_samples, get_snapshot, and get_context, though descriptions clarify map/no-map and task-context boundaries.
Naming Consistency4/5
Names are consistently snake_case and mostly follow a verb_noun pattern. A minor split exists between mason_* prefixed tools and unprefixed tools, and a few noun-like names such as full_analysis and mason_automation slightly break the pattern but remain readable.
Tool Count3/5
22 tools is at the heavy end for a single MCP server and falls into the borderline 16-25 range. The domain is complex, but some setup/lifecycle tools could likely be consolidated, so the set feels heavy rather than tightly scoped.
Completeness4/5
The surface covers setup, decision capture/review/retirement, map build/verification/drift, impact analysis, advisory review, and Confluence export, which is broad lifecycle coverage. Minor gaps exist around generic listing/deletion/update paths for some artifacts, but agents can generally work around them.
Maintenance
ActivityActive
ResponsivenessSlow
Related MCP Connectors
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.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
11
Related MCP Servers
- AlicenseAqualityCmaintenanceExtract 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 gradedqualityCmaintenanceTransforms codebases into structural knowledge graphs for AI agents and developers, providing precise architectural awareness and dependency mapping.54MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with persistent architectural memory of codebases, enabling impact analysis, test generation, and code generation with reduced token usage.MIT