feat(mcp): wave 7c — required-sections config tools

[thewrz]

Why

Wave 7 (config-CRUD parity, ADR-044), sub-wave 7c. Exposes the required-sections REST endpoints as MCP tools so an agent can define what sections a project/package is expected to contain — the input to the coordination_report's required-but-absent check.

What

Four tools, MCP_UNEXPOSED → OP_TO_TOOL:

Tool	Tier	REST op
get_required_sections	read	GET /projects/{id}/required-sections
set_required_sections	write	PUT /projects/{id}/required-sections
get_package_required_sections	read	GET /projects/{id}/packages/{packageId}/required-sections
set_package_required_sections	write	PUT /projects/{id}/packages/{packageId}/required-sections

• The set tools take either an explicit sections list (section + optional title, no dupes) or seedFrom (baseline / toc / { packageId }) — never both — reusing RequiredSectionsBodySchema's cross-field refine. The body is validated separately from the path ids so the refine survives (the schema strips the id keys).
• Handlers mirror the REST applyBody + seedSourceFrom and map the typed errors (project/package-not-found → not-found, seed-conflict, invalid-seed) to tool errors.
• No openapi.yaml change (wraps existing ops).

Review

• Codex (GPT-5.5 xhigh) adversarial review: no actionable findings — handlers, registration, tier map, and contract map all sound.

Testing

• Unit tests pass (1345)
• Integration tests pass (841) — incl. new required-sections.integration.test.ts (project + package set→get, sections-xor-seedFrom refine, duplicate rejection, missing project/package)
• Contract test green (INV-1/2/3 — 4 ops mapped + tiered)
• Lint clean
• CI green

🤖 Co-authored by Claude Opus 4.8. Part of the Wave 7 config-CRUD parity series (ADR-044/045).

Summary by CodeRabbit

• New Features
  • Added MCP tools to view and manage “required sections” at both project and package scope (get_*required_sections and set_*required_sections).
  • Reads and writes support configuring required sections either via an explicit sections list or a seed source (mutually exclusive).
• Bug Fixes
  • Improved tool error handling for invalid inputs, malformed identifiers, missing scope information, conflicting/duplicate configurations.
• Tests
  • Added integration tests covering set/get flows, seeding behavior, and expected rejection cases (including malformed UUIDs).

[thewrz]

Codex (GPT-5.5, xhigh) adversarial review — ran against main. No actionable correctness issues in the required-sections handlers, tool registration, tier map, or contract map. The sections-xor-seedFrom refine is preserved (validated separately from the path ids), and the typed not-found/seed-conflict/invalid-seed errors map cleanly to tool errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d731adb1-e990-4a63-b4ca-c4071d4e211f

📥 Commits

Reviewing files that changed from the base of the PR and between e80b0b5 and 6249ff9.

📒 Files selected for processing (2)

• src/mcp/required-sections-handlers.ts
• src/mcp/required-sections.integration.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• src/mcp/required-sections.integration.test.ts
• src/mcp/required-sections-handlers.ts

---

📝 Walkthrough

Walkthrough

This PR adds MCP tool support for required sections at project and package scope. It introduces new handlers, tool registrations, capability-tier entries, contract mappings, and integration tests for read/write required-sections operations.

Changes

Required-Sections MCP Tools

Layer / File(s)	Summary
Schemas and helper logic for required-sections handlers src/mcp/required-sections-handlers.ts	Defines Zod shapes for project/package scope and required-sections request bodies, plus helpers for seedFrom conversion, applying required sections, and mapping domain errors.
Get/Set request handlers for required sections src/mcp/required-sections-handlers.ts	Implements the four required-sections handlers for project and package scope, with validation, read/write calls, and tool-error handling.
Tool registration and MCP wiring src/mcp/required-sections-tools.ts, src/mcp/tools.ts, src/mcp/capabilities.ts, src/mcp/contract-map.ts	Registers the new tools, wires them into registerTools, adds capability tiers and operation-to-tool mappings, and removes the matching unexposed entries.
Integration tests for required-sections handlers src/mcp/required-sections.integration.test.ts	Adds database-backed tests for successful set/get flows and rejection cases across project and package scope.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant handleSetRequiredSections
  participant RequiredSectionsBodySchema
  participant applyRequiredSections

  Client->>handleSetRequiredSections: call with projectId + body
  handleSetRequiredSections->>RequiredSectionsBodySchema: safeParse(args)
  RequiredSectionsBodySchema-->>handleSetRequiredSections: parsed sections or seedFrom
  handleSetRequiredSections->>applyRequiredSections: apply scope + request data
  applyRequiredSections-->>handleSetRequiredSections: success or domain error
  handleSetRequiredSections-->>Client: ok(...) or toolError(...)

Loading

Possibly related PRs

• wrzonance/SpecR#239: Adds the required-sections REST-side behavior that the new MCP handlers and mappings mirror across project and package scope.
• wrzonance/SpecR#334: Shares the same MCP capability and contract-mapping framework updated here.
• wrzonance/SpecR#24: Also extends src/mcp/tools.ts to register an additional MCP tool group.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding MCP required-sections configuration tools.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-contract-wave7c

---

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/mcp/required-sections.integration.test.ts (1)

66-88: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing coverage for seedFrom and malformed-UUID paths.

The PR objectives call out seed-conflict and invalid-seed typed-error mappings, and the handlers distinguish malformed UUID input (toolError('... must be a UUID')) from well-formed-but-missing UUIDs (not-found business error). This suite only tests mutual exclusion and not-found via a valid-but-absent UUID (MISSING); it never exercises a successful seedFrom: 'baseline'/'toc'/{ packageId } set, a seed-conflict scenario, an invalid-seed value, or a syntactically invalid UUID string. These are meaningfully different code paths in the handlers (schema validation vs. business logic) and are worth covering given they're explicitly mentioned as handled behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mcp/required-sections.integration.test.ts` around lines 66 - 88, Add
integration coverage in required-sections tests for the seedFrom and UUID
validation branches handled by handleSetRequiredSections,
handleGetRequiredSections, and handleGetPackageRequiredSections. Extend the
suite to verify a successful seedFrom case for baseline/toc or a packageId seed,
plus a seed-conflict typed error and an invalid-seed typed error. Also add a
malformed UUID case distinct from the existing MISSING not-found check so the
toolError("... must be a UUID") path is exercised separately from the
business-not-found path.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp/required-sections-handlers.ts`:
- Around line 110-114: The package-scope UUID validation in the
required-sections handlers is using a fixed `toolError(...)` message, which
hides which field failed; update the `PackageScopeArgs.safeParse` failure path
to use `issues(...)` like the other multi-field handlers. Keep the validation
logic in `get_package_required_sections` and the corresponding package-scope
handler aligned so errors report the specific field issues for `projectId` and
`packageId`.

---

Nitpick comments:
In `@src/mcp/required-sections.integration.test.ts`:
- Around line 66-88: Add integration coverage in required-sections tests for the
seedFrom and UUID validation branches handled by handleSetRequiredSections,
handleGetRequiredSections, and handleGetPackageRequiredSections. Extend the
suite to verify a successful seedFrom case for baseline/toc or a packageId seed,
plus a seed-conflict typed error and an invalid-seed typed error. Also add a
malformed UUID case distinct from the existing MISSING not-found check so the
toolError("... must be a UUID") path is exercised separately from the
business-not-found path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8012b338-31eb-4b36-8e38-452e07d389fb

📥 Commits

Reviewing files that changed from the base of the PR and between 46b6b34 and 10328a5.

📒 Files selected for processing (6)

• src/mcp/capabilities.ts
• src/mcp/contract-map.ts
• src/mcp/required-sections-handlers.ts
• src/mcp/required-sections-tools.ts
• src/mcp/required-sections.integration.test.ts
• src/mcp/tools.ts

[thewrz]

CodeRabbit nitpick addressed. The seedFrom/seed-conflict/invalid-seed coverage gap was closed in e80b0b5 — required-sections.integration.test.ts now exercises a successful seedFrom: 'baseline' (package), seedFrom: { packageId } (package-from-package), an invalid-seed rejection (baseline may only seed from 'toc'), and a seed-conflict (seeding an already-populated scope). The remaining path — a syntactically malformed UUID (schema-validation, distinct from valid-but-absent not-found) — is now covered in 6249ff9.