# nova.mcp-bcp-counting

> MCP Server for **BCP Plus** complexity counting — 10 functional + 3 non-functional dimensions.

Built on the [BCP Plus methodology](https://docs.google.com/document/d/10MfqjlmiOOD1Oz0NJVoHq4Y2jg7dBujQ42afYU9RQFI/edit) (CI&T, May 2026). Enables Claude to guide developers through structured complexity estimation during planning or coding sessions in VSCode, Claude Code, and Cursor.

---

## What it does

When a developer asks Claude to count BCP for a story, Claude automatically:

1. **Assesses story maturity** — warns if the story is too vague to count reliably
2. **Counts each dimension in isolation** — 1 prompt per dimension, reducing cross-dimensional interference (per whitepaper recommendations)
3. **Calculates BCP Plus total** — Functional BCP + NFR BCP + NFR Ratio + risk classification
4. **Persists the result** — saves to `.bcp/counts.json` in the project for H/BCP tracking

---

## Quick start

### Prerequisites

- Node.js ≥ 18
- One of: VSCode, Claude Code, or Cursor

### Install

```bash
# Clone and build
git clone https://github.com/danielvm-git/nova.mcp-bcp-counting.git
cd nova.mcp-bcp-counting
npm install
npm run build

# Install for your platform
node dist/installer/install.js --platform vscode       # VSCode
node dist/installer/install.js --platform claude-code  # Claude Code
node dist/installer/install.js --platform cursor       # Cursor

# Or interactive (asks which platform)
node dist/installer/install.js
```

### Use

Open a story file or paste it in the chat, then ask Claude:

```
Count the BCP Plus for this story.
```

```
Decompose this epic into stories and estimate the BCP for each.
```

```
Show me the project BCP metrics so far.
```

---

## The 13 dimensions

### Functional (D01–D10) — inherited from BCP open-source release

| # | Dimension | CV% | Stability |
|---|-----------|-----|-----------|
| D01 | Business Rules | 19.2% | Moderate |
| D02 | Interface Elements | 40.1% | High ⚠️ |
| D03 | Roles / Permissions | 33.2% | High ⚠️ |
| D04 | Solution Variabilities | 47.1% | Critical 🔴 |
| D05 | Boundaries | 44.6% | Critical 🔴 |
| D06 | Domain Entities | 38.6% | High ⚠️ |
| D07 | New Domain Entities | 24.8% | Moderate |
| D08 | Background Processes | 21.4% | Moderate |
| D09 | Notifications | 13.5% | Stable ✅ |
| D10 | Audits | 13.2% | Stable ✅ |

### Non-functional (D11–D13) — BCP Plus exclusive

| # | Dimension | CV% | Stability |
|---|-----------|-----|-----------|
| D11 | Quality Attributes | 22.5% | Moderate |
| D12 | Security & Compliance | 10.5% | Stable ✅ |
| D13 | UX & Accessibility | 9.8% | **Most stable** ✅ |

> CV% = coefficient of variation from the 43-story empirical baseline (CI&T Flow team, April 2026).  
> D04 and D05 are flagged as LOW CONFIDENCE in all outputs — always validate with the team.

### Fibonacci scale

| Label | Score |
|-------|-------|
| XS | 1 |
| S | 2 |
| M | 3 |
| L | 5 |
| XL | 8 |

---

## NFR Ratio risk levels

| NFR Ratio | Risk | Action |
|-----------|------|--------|
| 0–15% | Primarily functional | Standard delivery |
| 15–30% | Balanced | Monitor NFR during sprint |
| 30–50% | NFR-heavy 🟡 | Architectural spike recommended |
| >50% | Extreme 🔴 | Architectural review required |

---

## Available MCP tools

| Tool | Description |
|------|-------------|
| `assess_story_maturity` | Score story maturity 1–5 and get expected CV% |
| `list_dimensions` | List all 13 dimensions with stability status |
| `get_dimension_guide` | Full sizing criteria + per-dimension prompt for a given D-id |
| `count_dimension` | Get counting context for a dimension (used by Claude per-dimension) |
| `calculate_bcp_plus` | Aggregate scores → Functional + NFR + NFR Ratio + risk |
| `decompose_epic` | Get guidance to split an epic into well-sized stories |
| `save_story_count` | Persist a count to `.bcp/counts.json` |
| `get_project_metrics` | Read all saved counts and project totals |

---

## Story maturity and counting reliability

Story maturity is the strongest predictor of counting accuracy:

| Maturity | Expected CV | Recommendation |
|----------|-------------|----------------|
| < 3 | ~39.5% | ⚠️ Do not count — refine first |
| = 3 | ~15.5% | Acceptable — flag open items |
| > 3 | ~12.2% | ✅ Ready to count |

A story reaches maturity 3+ when it has:
- A defined actor
- Clear acceptance criteria (Given/When/Then)
- Business value stated
- Key entities named

---

## Project metrics

After counting stories, BCP data is saved locally in `.bcp/counts.json`:

```json
{
  "project": "my-project",
  "summary": {
    "story_count": 12,
    "total_bcp": 148,
    "avg_bcp_per_story": 12.3,
    "avg_nfr_ratio_pct": 18.5
  },
  "stories": [...]
}
```

Use `total_bcp` + actual delivery hours to compute **H/BCP** (hours per BCP point) — the key productivity indicator for AI-augmented teams.

---

## Platform config files generated

| Platform | File |
|----------|------|
| VSCode | `.vscode/mcp.json` |
| Claude Code | via `claude mcp add` |
| Cursor | `.cursor/mcp.json` |

---

## References

- [BCP Plus Whitepaper](https://docs.google.com/document/d/10MfqjlmiOOD1Oz0NJVoHq4Y2jg7dBujQ42afYU9RQFI/edit) — Daniel Vieira Magalhães, CI&T, May 2026
- [ScopeCounting](https://github.com/dpetruz/ScopeCounting) — related scope counting tooling
- [BCP open-source release](https://github.com/search?q=business+complexity+points+ciandt) — CI&T & Itaú Unibanco, MIT License, May 2026

---

## License

MIT — © CI&T