adrianczuczka/mason

npm version CI npm downloads license issues

A persistent concept map for your AI coding assistant — so it stops re-exploring your codebase every session.

Up to 67% fewer tokens on architecture questions · same answer quality · MCP-only

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

Restart Claude Code, then ask: "use mason to set up this project." The assistant calls mason_init, walks you through a quick Q&A to build the concept map, and you're done.

Next session, your assistant loads the map instead of grepping 8 files to figure out what your app does.

0.4.0 note: Mason is MCP-only as of v0.4.0. The previous mason <command> CLI has been removed — everything runs through MCP tools, driven by your assistant. See 0.4.0 migration below if you used the old CLI.

The pain

Every new conversation about your code, your assistant starts from zero. It greps for auth, reads three files, greps for user, reads three more, pieces together the architecture, then finally answers. Tomorrow you ask a different question — same dance. The understanding it built yesterday is gone.

The fix

Mason persists a feature-to-file map in .mason/snapshot.json. One MCP tool call returns:

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

The assistant jumps straight to the relevant files instead of exploring.

Where the map comes from: Mason doesn't parse your code. Your assistant reads the project through Mason's analysis tools (analyze_project, get_code_samples, full_analysis) and writes the map itself. That means it captures architectural intent — what the code is for — not just symbols and call edges.

Benchmark

deepeval, Claude Sonnet, 164-file Kotlin Multiplatform project:

Same answer quality (0.9/1.0 on every question, both paths). Reproduce: bench/.

MCP tools

The init / write tools refuse to run until mason_init has completed. The read-only diagnostics (analyze_project, full_analysis, get_code_samples) work without init.

How the concept map is built

To stay accurate on codebases of any size, Mason uses a Map-Reduce pattern instead of stuffing the whole codebase into one LLM call:

• Map: generate_snapshot_batch returns ~50 files at a time (skeletons of every file in the batch plus a few deeper-read bodies for grounding). Your assistant produces a partial concept map for that batch and persists it with save_partial_snapshot. Repeat until every file in the project has been visited.
• Reduce: reduce_snapshot returns all the partials plus instructions to merge them into one product-shaped catalog — combining platform variants ("home Android" + "home iOS" → "home screen"), deduplicating, and ensuring no file is dropped.
• Save: save_snapshot persists the unified map and cleans up the partials.

The result: every source file is represented exactly once in the final snapshot. A 200-file project takes ~5 batches; a 1000-file monorepo takes ~20.

Change impact

Before editing a file, Mason tells you what else might be affected. Three signals you'd normally need a dozen tool calls to gather, in one call:

• Co-change history — files that historically change together in commits
• References — files that import or mention the target by name
• Related tests — test files paired by naming convention

Ask your assistant "what would be affected if I changed WeatherRepository?" and it'll call get_impact for you.

Other clients

Mason's MCP server is client-agnostic. Pick yours:

{
  "mcpServers": {
    "mason": {
      "command": "npx",
      "args": ["-p", "mason-context", "mason-mcp"]
    }
  }
}

{
  "mcpServers": {
    "mason": {
      "command": "npx",
      "args": ["-p", "mason-context", "mason-mcp"]
    }
  }
}

[mcp_servers.mason]
command = "npx"
args = ["-p", "mason-context", "mason-mcp"]

{
  "mcp": {
    "servers": {
      "mason": {
        "command": "npx",
        "args": ["-p", "mason-context", "mason-mcp"]
      }
    }
  }
}

Language support

Language-agnostic. Mason works from file naming patterns and git history rather than language-specific parsing, so it runs on any project with a git repo — TypeScript, Kotlin, Python, Go, Rust, Swift, Java, C#, Dart, and more.

Security

• The snapshot contains: feature names, relative file paths, flow descriptions. No source code, no secrets, no business logic.
• Respects .gitignore via git ls-files. A deny-list blocks .env, .pem, .key, credentials, and other sensitive files from being sampled.
• Path traversal protection keeps all file access inside the project root.
• MCP tools are local-only. Generating a snapshot via MCP uses your assistant's existing LLM context — Mason itself makes no API calls.

0.4.0 migration

If you used Mason before v0.4.0, the standalone mason <command> CLI has been removed. Everything now runs through MCP tools, called by your assistant.

The npm package is still published, but only the mason-mcp binary is meaningful now. Running mason directly prints a migration message and exits.

License

MIT