eazy-ba

A personal Business Analyst as an MCP server.

eazy-ba fills the BA role for solo engineers and small teams: it captures requirements, keeps them organized as plain markdown, and tracks the relationships between personas, requirements, use cases, and user stories so the documentation stays coherent as a project evolves.

Markdown files are the single source of truth — everything lives under docs/ba/, is human-readable, git-diffable, and hand-editable. Relationships are stored in YAML frontmatter, so traceability is always derived, never hand-maintained.

Status: Phase A (interrogative loop). eazy-ba now conducts structured BA interviews before writing anything — every requirement traces back to a decision you made.

Install

Add it to Claude Code with one command — no global install needed:

claude mcp add eazy-ba -- npx -y eazy-ba

That's it. npx fetches and runs the latest version on demand.

<details> <summary>Other MCP clients (manual config)</summary>

Register it as a stdio MCP server:

{
  "mcpServers": {
    "eazy-ba": {
      "command": "npx",
      "args": ["-y", "eazy-ba"]
    }
  }
}

</details>

The docs structure

Running ba_init scaffolds:

docs/ba/
├── _index.md                  # status dashboard
├── _config.yml                # docs root + id conventions
├── 01-vision/                 # vision.md, glossary.md
├── 02-stakeholders/personas/  # PER-001-*.md
├── 03-requirements/
│   ├── functional/            # FR-001-*.md
│   └── non-functional/        # NFR-001-*.md
├── 04-use-cases/              # UC-001-*.md
├── 05-stories/                # US-001-*.md (story + Gherkin acceptance criteria)
├── 06-analysis/               # traceability, gap-report, risks, assumptions
└── 07-changelog/              # requirement change history

Stable IDs (FR-001, US-001, PER-001, …) are the backbone; cross-links live in frontmatter (implements, satisfies, refines).

How it works — the interrogation loop

eazy-ba behaves like a Business Analyst: it asks before it writes, and never assumes.

1. ba_session_start — begin discovery (new project) or stabilize (tighten an existing one).
2. ba_assess — returns the questions to ask you. It writes nothing.
3. You answer; ba_record_answers saves each answer as a traceable decision (DEC-###).
4. ba_apply — turns those decisions into documents. Every document cites the decisions behind it; nothing is written without a recorded answer.
5. Repeat until ba_status reports stable (no open questions, no gaps).

Every requirement, story, and acceptance criterion traces back to a decision you made.

Tools

Tool	Purpose
ba_init	Scaffold the docs/ba/ tree in a project.
ba_session_start	Start or resume a BA session (mode: discovery | stabilize).
ba_assess	Analyze current state; return prioritized questions to ask the user. Creates nothing.
ba_record_answers	Save the user's answers as traceable decisions (DEC-###).
ba_apply	Materialize/update documents from recorded decisions. Rejects artifacts with no derived_from.
ba_status	Report open questions, gaps, pending decisions, and overall stability.
ba_get	Fetch one artifact by ID.
ba_list	List/filter artifacts by type, status, priority, or tag.

Each artifact carries MoSCoW priority (must / should / could / wont) and a status (draft → reviewed → approved → implemented / obsolete).

Configuration

docs/ba/_config.yml:

docsRoot: docs/ba   # relative to the project root, or an absolute path
idStart: 1          # first numeric ID

Roadmap

• Phase 2 — Analysis: deterministic structural gap detection + shipped BA checklists, requirement quality linting, traceability matrix generation, change impact analysis.
• Phase 3 — Smoothers: intake from brain dumps, adaptive elicitation interviews, codebase grounding, and Mermaid visualizations.

Development

npm install
npm test        # vitest, TDD throughout
npm run build   # tsc -> dist/

License

MIT