@massu/core

AI Engineering Governance MCP Server — session memory, feature registry, code intelligence, and rule enforcement for AI coding assistants.

Quick Start

npx massu init

This sets up the MCP server, configuration, and lifecycle hooks in one command.

What is Massu?

Massu is a source-available Model Context Protocol (MCP) server that adds governance capabilities to AI coding assistants like Claude Code. It provides:

• 73 MCP Tools — quality analytics, cost tracking, security scoring, dependency analysis, and more
• 15 Lifecycle Hooks — pre-commit gates, security scanning, intent suggestion, session management, and auto-learning pipeline
• 3-Database Architecture — code graph (read-only), data (imports/mappings), and memory (sessions/analytics)
• Config-Driven — all project-specific data lives in massu.config.yaml

Usage

After npx massu init, your AI assistant gains access to all governance tools automatically via the MCP protocol.

# Health check
npx massu doctor

# Validate configuration
npx massu validate-config

Permission Seeding

To skip the per-tool MCP permission dialog on a fresh install, npx massu install-commands automatically seeds the canonical glob mcp__massu__* into .claude/settings.local.json's permissions.allow array. It also propagates the user-global defaultMode (from ~/.claude/settings.json) into the project-local file (see "Permissions trap" below).

Three lifecycle subcommands for managing the allowlist:

# Seed the canonical entry + propagate global defaultMode (idempotent)
npx massu permissions install

# Read-only check — exit 0 if all canonical entries present
npx massu permissions verify

# Extended diagnostic — surfaces 4 drift kinds with severity-mapped exit codes
npx massu permissions check-drift

To opt out of automatic permission seeding during install-commands (e.g., when permissions are managed centrally by enterprise policy):

npx massu install-commands --skip-permissions

defaultMode validity reference (per Claude Code docs):

| Mode | Activatable from settings file alone | Requires launch flag | |---|---|---| | default | ✓ | — | | acceptEdits | ✓ | — | | plan | ✓ | — | | bypassPermissions | — | --permission-mode bypassPermissions or --dangerously-skip-permissions | | auto | — | --permission-mode auto (plus plan/admin/model preconditions) | | dontAsk | — | --permission-mode dontAsk |

permissions check-drift warns when a launch-flag-required value is set in settings without the corresponding flag (these settings are silently inert without the launch flag).

Permissions trap (settings merge)

Empirically observed in Claude Code 2.1.x: a project-local .claude/settings.local.json that has a permissions object without a defaultMode key silently STRIPS the user-global defaultMode from ~/.claude/settings.json during settings merge. The merge unit appears to be the entire permissions object's top-level keys, not individual keys within it — undocumented at code.claude.com/docs/en/permissions.

Before (trap state):

// ~/.claude/settings.json (global)
{ "permissions": { "defaultMode": "auto" } }

// .claude/settings.local.json (project)
{ "permissions": { "allow": ["mcp__massu__*"] } }
// Effective defaultMode in this project: NONE (global "auto" silently stripped)

After (correct state, what massu permissions install writes):

// .claude/settings.local.json (project)
{ "permissions": {
    "allow": ["mcp__massu__*"],
    "defaultMode": "auto"
} }

The install writer:

1. Reads global ~/.claude/settings.json
2. Reads project-local .claude/settings.local.json
3. Computes merged state: allow = union with canonical entries; defaultMode = local override OR global value OR omit; deny/ask preserved from local
4. Atomic-writes the complete merged block
5. Post-write fail-loud assertion: re-reads disk and confirms the merge survived

To audit any project for the trap (or any other permission drift):

npx massu permissions check-drift
# Exit 4 + stderr "drift[strips-global-defaultmode]: ..." if the trap is present

Changelog Generation

Release-boundary CHANGELOG entries are auto-drafted by npx massu changelog generate (shipped 1.9.0+). The generator reads commit subjects since the last git tag, groups them by (plan-<token>) paren-notation (the same convention enforced by CR-40), and pulls each plan file's ## Changelog Summary section verbatim into a Keep-a-Changelog 1.1.0-compliant entry. Goal: "fewer changelog entries, more meaningful" — one entry per release, structured by plan-token, instead of per-commit noise.

# Auto-draft entry for commits since the last tag
npx massu changelog generate > /tmp/draft-entry.md

# Read-only verify that the latest CHANGELOG entry references every plan-token
# in the commit range since the last tag
npx massu changelog verify

Plan-file ## Changelog Summary contract: any plan whose Status is in the shipped subset (SHIPPED, IMPLEMENTED, COMPLETE, SUPERSEDED, APPROVED) MUST contain a ## Changelog Summary section. The plan-status validator (scripts/massu-plan-status-validator.sh) enforces this — plans missing the section fail validation. The release generator reads this section to produce the CHANGELOG entry body, so plan authors describe shipped behavior once (in the plan file) and the generator propagates it.

Pre-tag gate: scripts/pre-push-light.sh step [11/11] Plan-Token Changelog Currency fires when packages/core/package.json#version drifts from the latest git tag (i.e., a release is in progress). The gate BLOCKS the push if CHANGELOG.md doesn't have a ## [X.Y.Z] heading matching the new version AND doesn't reference every plan-token in the commit range since the last tag. The CI workflow at .github/workflows/ci.yml mirrors this check (3-layer enforcement: pre-push + CI + drift-guard vitest).

Documentation

Full documentation at massu.ai.

License

BSL 1.1 — source-available. Free to use, modify, and distribute. See LICENSE for full terms.