<div align="center">

Momus-MCP

The ultimate critic among the deities — pointed at your test suite.

</div>

Momus (Μῶμος) is the ancient Greek spirit and personification of satire, mockery, blame, and harsh criticism — the one god whose entire job was to find fault, and who was finally thrown off Olympus for doing it too well. His name literally translates to "blame" or "censure".

Momus-MCP is a local-first, deterministic, read-only MCP server and CLI that audited test suites the way Momus audited the gods: ruthlessly, and with no tolerance for things that pass while proving nothing. It hunts false-green tests — suites that go green because of tautological assertions, mock-contract drift, and mock-hygiene problems, not because the code works. The name is doubly apt: Momus is the god of mockery, and mock objects are exactly what this tool scrutinizes.

Status: pre-release. Momus-MCP is not yet published to npm — the publish step in the release workflow is deliberately dormant (credential-blocked). The source is public; install from source (see Quick Start). Any npx @momus/* command you find elsewhere will not resolve until the packages are published.

---

Why Momus-MCP?

Coding agents are great at writing tests. They are also great at writing tests that can never fail — asserting a mock's own configured return value, stubbing a method that no longer exists, or comparing a value with itself. The result is a suite that is green and useless.

Momus-MCP statically detects these. It never executes your code, never talks to the network, and never writes to your workspace. It just reads the source, builds a symbol graph of your production code, and checks every mock, spy, and assertion against it.

Relentless detection

Category	Rules	What it catches
Tautological assertions	TAUT-001…006	self-comparison, mock-echo (asserting a stub's own return), constant-tautology, mock-only assertions, zero-reach stubs, unconfigured-spy assertions
Mock-contract drift	DRIFT-000…006	unresolvable targets, missing members, signature mismatches, return-type mismatches, constructor drift, missing exports, stale mocks (git-diff aware)
Mock hygiene	MOCK-001/002	over-mocking (saturation), mocking the module under test

Deterministic by contract

• Read-only — every tool is annotated readOnlyHint: true, destructiveHint: false.
• Deterministic — byte-identical output for an identical workspace (golden-tested).
• Token-budgeted — every finding renders in < 100 tokens (unit-tested).
• Zero false positives on the reference healthy suite — anti-pattern fixtures ship with a healthy twin, and both are asserted in CI.
• Zero runtime dependencies in @momus/core — the engine is pure TypeScript.

Four languages, one engine

• TypeScript / JavaScript — Vitest and Jest (vi.mock, vi.fn, vi.spyOn, vi.mocked, jest.mock, object-literal and Proxy doubles, automock helpers).
• PHP — PHPUnit, Pest, and Mockery (createMock, getMockForAbstractClass, mock(), Mockery::mock, closure-form mocks, docblock @param/@return typing, Composer PSR-4 and classmap resolution).
• Python — pytest and unittest (patch, patch.object, Mock(spec=), mocker, monkeypatch, assert/pytest.raises), PEP 484/526/585/604 annotation typing (opt-in via languages.python).
• Rust — mockall (#[automock], mock!, expect_*().returning()), mockito, wiremock, and built-in assert!/assert_eq!/assert_ne!/assert_matches!, via a syn-to- WASM parser with a crate-wide index for semantic-from-day-one drift checking (opt-in via languages.rust).

---

Quick Start

Requirements: Node.js ≥ 20.

git clone <this repository>
cd momus-mcp
npm ci
npx momus audit .

Momus exits with:

Code	Meaning
0	no error-level findings
1	error-level findings present
2	usage or configuration error
3	unexpected internal error

Once published, the same experience is a one-liner:

npx momus audit .            # Markdown report; exit 1 on errors
npx momus audit . --json     # machine-readable JSON envelope

Useful commands

npx momus audit .                        # full audit (tautology + drift + hygiene)
npx momus audit tests/order.test.ts      # scope to specific paths
npx momus drift                          # mock-contract drift only
npx momus precommit                      # drift on uncommitted changes (git-diff scope)
npx momus hook --install --yes           # install the pre-commit drift gate
npx momus annotate                       # JSONL findings for editor plugins
npx momus contract src/services/ledger.ts  # synthesize a strict mock from a real class
npx momus rules                          # list rules and severities
npx momus init                           # scaffold a .momusrc config
npx momus doctor                         # inspect the local setup
npx momus serve                          # run the MCP server (stdio)
npx momus serve --transport http --port 3000  # Streamable HTTP transport
npx momus serve --watch                  # re-audit on file changes (chokidar)

---

MCP server

Momus speaks stdio (default) or Streamable HTTP, and is read-only. Point it at a workspace with MOMUS_ROOT.

Claude Desktop

{
  "mcpServers": {
    "momus": {
      "command": "npx",
      "args": ["-y", "@momus/mcp-server"],
      "env": {
        "MOMUS_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor and other MCP clients

The same shape works in any MCP client:

{
  "command": "npx",
  "args": ["-y", "@momus/mcp-server"],
  "env": {
    "MOMUS_ROOT": "/absolute/path/to/your/project"
  }
}

Tools

Tool	What it does
audit_test_fidelity	Deep audit of a test file: every mock/spy/stub checked against its real production dependency
detect_tautological_assertions	Find assertions that cannot fail
verify_mock_drift	Find test doubles that no longer match production (supports scope: git-diff)
synthesize_mock_contract	Generate a strict typed mock template from a real class/interface
list_rules	The rule catalog with severities

---

Use cases

• Agent guardrails — drop Momus into a coding agent's loop and block it from committing a test that "passes" by echoing the mock it just configured.
• Pre-commit drift gate — momus hook --install (or precommit in CI) fails the commit the moment a production rename leaves a test double behind.
• Mock-contract generation — point synthesize_mock_contract at a class and get a typed, satisfies Partial<T> template instead of hand-writing as any stubs.
• PHP parity — the same rules for PHPUnit/Pest suites, including constructor drift and docblock-typed returns.

---

How it works

flowchart LR
    Source[Test + Production Source] --> Parser[Language Parsers]
    Parser --> IR[Normalized IR]
    IR --> Index[SymbolIndex]
    Index --> Rules[Rules Engine]
    Rules --> Report[Markdown / JSON / JSONL]

1. Discover source and test files (capped, gitignore-aware).
2. Parse each file into a language-neutral IR (TypeScript via the compiler API, PHP via php-parser) — a persistent better-sqlite3 cache keyed by content hash + workspace digest makes warm audits fast.
3. Index production symbols into a graph of classes, interfaces, members, and signatures.
4. Run rules — every mock and assertion is checked against the real production contract; findings are suppression-aware and rendered under a token budget.
5. Report — Markdown, a JSON envelope, or JSONL for editor plugins, with honest exit codes.

---

Configuration

Momus reads .momusrc from the workspace root. npx momus init scaffolds one:

{
  "languages": { "typescript": true, "php": false },
  "testFilePatterns": ["**/*.{test,spec}.{ts,tsx,js,jsx,mjs}", "**/__tests__/**"],
  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "rules": {
    "TAUT-002": { "severity": "error" }
  },
  "tokenBudget": { "maxIssuesPerReport": 50, "maxIssueLineTokens": 100 },
  "cache": { "dir": ".momus/cache", "enabled": true }
}

Intentional exceptions are marked in source:

// @momus-ignore:TAUT-002
expect(result).toEqual(configuredValue);

See the specification for the complete suppression grammar (line, trailing, docblock, file-banner) and the full configuration schema (schemas/momusrc.schema.json).

---

Documentation hub

Document	Contents
docs/README.md	Specification index and project status
docs/02-architecture.md	Parsing strategy, IR, symbol index, mock catalog
docs/03-analysis-algorithms.md	Rule catalog and detection algorithms
docs/04-mcp-tool-definitions.md	MCP tool schemas and agent protocol
docs/05-output-format.md	Issue grammar and Markdown/JSON schemas
docs/10-build-plan.md	Implementation status and sequenced plan
HANDOVER.md	Current engineering handover

---

Development

npm ci
npm run typecheck     # 0 errors across all packages
npm test              # vitest: unit + integration + golden suites
npm run test:coverage # v8 coverage with floors (80% stmts/lines, 75% branches, 90% funcs)
npm run lint          # ESLint (flat config, typescript-eslint)
npm run format:check  # Prettier
npm run audit-self    # Momus audits its own repo — must stay CLEAN

The repository is an npm workspace. Package sources run directly from TypeScript during this pre-publish phase; npx momus resolves through the workspace bin after npm ci.

License

Released under the MIT License — free for any use, commercial included. It speaks any MCP client, not just Claude Code, and reads code you already have. Like its namesake, it will tell you exactly what is wrong — politely is not in the job description.