scaffold-ca-python 0.4.0__tar.gz → 0.5.0__tar.gz

scaffold_ca_python-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{scaffold_ca_python-0.4.0 → scaffold_ca_python-0.5.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.4.0...v0.5.0) (2026-10-27)
+
+
+### Features
+
+* **mcp:** generate health check route for MCP entry points ([70a2645](https://github.com/bancolombia/scaffold-clean-architecture-py/commit/70a2645e63957d211761e7535edc675685031d57))
+
 ## [0.4.0](https://github.com/bancolombia/scaffold-clean-architecture-py/compare/v0.3.0...v0.4.0) (2026-10-26)
 
 

{scaffold_ca_python-0.4.0 → scaffold_ca_python-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scaffold-ca-python
-Version: 0.4.0
+Version: 0.5.0
 Summary: Scaffolder to generate Clean Architecture apps
 Project-URL: Homepage, https://github.com/bancolombia/scaffold-clean-architecture-py
 Project-URL: Repository, https://github.com/bancolombia/scaffold-clean-architecture-py

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: MCP Entry Point Health Check Route
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-26
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) — see Notes
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders — see Notes
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification — see Notes
+
+## Notes
+
+- This CLI is a code generator, so the generated artifact (file path, function name, route path, response body) **is** the user-facing contract. The reference `routes.py` in FR-013 was supplied by the requester and is kept intentionally; framework names appear only where they define the generated output.
+- Route binding must happen before the MCP HTTP app is built (FR-006): `start_server()` materializes routes when it builds the MCP HTTP app, while tools/resources/prompts are bound inside the lifespan. Binding the health route in the lifespan would leave it unregistered.
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`.

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/contracts/generated-routes.md

@@ -0,0 +1,83 @@
+# Contract: Generated MCP Health Route
+
+**Feature**: `027-mcp-health-check`
+
+The CLI's public interface (`gep --type mcp` and its flags) does not change. The contract below describes the **generated output**, which is what consumers depend on.
+
+## 1. HTTP contract (generated server)
+
+| Request | Status | Body |
+|---|---|---|
+| `GET /api/v1/health` | `200` | `{"status": "ok"}` (`application/json`) |
+| `HEAD /api/v1/health` | `200` | empty |
+| `POST`/`PUT`/`DELETE`/`PATCH /api/v1/health` | `405` | Starlette default |
+
+- No authentication.
+- Served on the same `HOST`/`PORT` as the MCP endpoint (`/mcp`).
+
+## 2. Generated `routes.py`
+
+Path: `src/<pkg>/infrastructure/entry_points/mcp_server/routes.py`
+
+```python
+"""MCP custom routes binding — register non-MCP HTTP routes such as the health check."""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+
+def bind_routes(mcp: FastMCP) -> None:
+    """
+    Bind routes to the FastMCP instance.
+    """
+
+    @mcp.custom_route(name="health_check", path="/api/v1/health", methods=["GET"])
+    async def health_check(_request: Request) -> Response:
+        """
+        Health check endpoint to verify the server is running.
+
+        Returns:
+            JSON response indicating the server is healthy.
+        """
+
+        response_data = {"status": "ok"}
+        return JSONResponse(response_data)
+```
+
+The file must pass the generated project's `ruff check` (`E`, `F`, `I`, `UP`, `ANN`).
+
+## 3. Generated `app.py` delta
+
+```python
+from {{ project.python_package }}.infrastructure.entry_points.mcp_server import routes, tools
+# ... optional resources / prompts imports unchanged ...
+
+mcp: FastMCP = FastMCP("{{ project.name }}", stateless_http=True)
+routes.bind_routes(mcp)
+```
+
+- `lifespan` is unchanged. `routes` is **not** added to `container.wire(...)`.
+- `start_server()` is unchanged and MUST NOT call `bind_routes`.
+
+## 4. Generated tests
+
+- **`test_routes.py`** (new):
+  - `bind_routes(FastMCP("test"))` registers `/api/v1/health`.
+  - `GET` returns 200 with `{"status": "ok"}`.
+  - `POST` returns 405.
+  - Uses `starlette.testclient.TestClient` without starting the lifespan.
+- **`test_app.py`** (modified):
+  - After calling `start_server()` twice, `/api/v1/health` appears exactly once in the mounted app's routes.
+  - `TestClient(start_server()).get("/api/v1/health")` returns 200 with `{"status": "ok"}`, without starting the lifespan.
+
+## 5. CLI dry-run contract
+
+`gep --type mcp --dry-run` lists, in addition to the current files:
+
+```text
+src/<pkg>/infrastructure/entry_points/mcp_server/routes.py
+<tests_root>/infrastructure/entry_points/mcp_server/test_routes.py
+```

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/data-model.md

@@ -0,0 +1,31 @@
+# Data Model: MCP Entry Point Health Check Route
+
+**Feature**: `027-mcp-health-check`
+
+This feature adds no domain models, Pydantic context models, or persisted data. The only "data" is the generated HTTP contract and the files queued by the factory.
+
+## Health Response (generated project)
+
+| Field | Type | Value | Rule |
+|---|---|---|---|
+| `status` | string | `"ok"` | Always `"ok"` when the process serves HTTP; no other fields. |
+
+- Served at `GET /api/v1/health` (also `HEAD`, added automatically by Starlette).
+- Content type `application/json`, HTTP 200.
+- Any other method returns HTTP 405.
+- It is a stateless liveness signal: it does not depend on the DI container, the domain, or driven adapters.
+
+## Template Context (CLI)
+
+`routes.py.jinja2` and `test_routes.py.jinja2` reuse the existing module context (`builder.module_ctx.model_dump()`, i.e. `project.python_package`, `project.name`) already passed to the other `entry_point/mcp/` templates. No new context fields or Pydantic models are introduced (Principle II is unaffected).
+
+## Files Queued by `EntryPointMcp.build()`
+
+| Path | Template | Condition | Change |
+|---|---|---|---|
+| `src/<pkg>/infrastructure/entry_points/mcp_server/routes.py` | `entry_point/mcp/routes.py.jinja2` | always | **NEW** |
+| `<tests_root>/infrastructure/entry_points/mcp_server/test_routes.py` | `entry_point/mcp/test_routes.py.jinja2` (`is_test=True`) | always | **NEW** |
+| `src/<pkg>/application/app.py` | `entry_point/mcp/app.py.jinja2` | always | MODIFIED: import `routes`; `routes.bind_routes(mcp)` after `mcp` creation |
+| `<tests_root>/infrastructure/entry_points/mcp_server/test_app.py` | `entry_point/mcp/test_app.py.jinja2` | always | MODIFIED: asserts health route registered exactly once and reachable through `start_server()` |
+
+All other queued files, dependencies, and overwrite flags are unchanged. The new files use the default `overwrite=False`, the same as `tools.py`.

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/plan.md

@@ -0,0 +1,106 @@
+# Implementation Plan: MCP Entry Point Health Check Route
+
+**Branch**: `feature/mcp-health-check` | **Date**: 2026-10-26 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `/specs/027-mcp-health-check/spec.md`
+
+## Summary
+
+Make `gep --type mcp` always generate `infrastructure/entry_points/mcp_server/routes.py`.
+
+- **Route**: `routes.py` exposes a synchronous `bind_routes(mcp)` that registers an async `health_check` custom route (`GET /api/v1/health` returns `{"status": "ok"}`) via `FastMCP.custom_route`.
+- **Wiring**: The generated `app.py` calls `routes.bind_routes(mcp)` once at module level, right after creating `mcp`, so the route is in place before `start_server()` builds the MCP HTTP app and is never duplicated.
+- **Tests**: The feature ships a generated `test_routes.py`, extends the generated `test_app.py`, and adds CLI-side template, factory, and dry-run-baseline tests.
+- **Scope**: Two new Jinja2 templates and a small edit to `EntryPointMcp.build()`. No new dependencies, flags, or CLI surface.
+
+## Technical Context
+
+**Language/Version**: Python 3.13+ (no change)
+
+**Primary Dependencies**:
+- CLI: Typer, Rich, Jinja2, Pydantic v2 (unchanged).
+- Generated project: the existing `mcp~=1.30.0` (`FastMCP.custom_route`) and `starlette~=1.6.0` (`Request`, `JSONResponse`, `TestClient`).
+- `httpx` for `TestClient` is already a transitive dependency of `mcp`.
+- **No new dependency.**
+
+**Storage**: N/A
+
+**Testing**:
+- CLI: pytest + pytest-cov (≥ 80% gate), in `tests/templates/`, `tests/factory/entry_points/`, and `tests/factory/` (dry-run parity).
+- Generated project: pytest with Starlette `TestClient`.
+
+**Target Platform**: Cross-platform CLI; generated server runs under uvicorn (unchanged)
+
+**Project Type**: Single project — CLI code generator (template + factory change)
+
+**Performance Goals**: N/A (constant-time health response; CLI generation time unchanged)
+
+**Constraints**:
+- `bind_routes` MUST run before `mcp.streamable_http_app()` is called and exactly once per process. It is called at module level, not inside `start_server()` or `lifespan` ([research R2](./research.md#r2--when-to-call-bind_routesmcp)).
+- Generated `routes.py`/`test_routes.py` MUST pass the generated project's `ruff` (`E`, `F`, `I`, `UP`, `ANN`; tests ignore `ANN`).
+- MUST NOT change `tools.py.jinja2`, the `--add-tool` path, flags, dependencies, or overwrite policy.
+
+**Scale/Scope**:
+- 2 new templates and 3 modified files (`ep_mcp.py`, `app.py.jinja2`, `test_app.py.jinja2`).
+- 1 fixture update and test additions in 2 CLI test files.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Check | Result |
+|---|---|---|
+| I. Clean Architecture in Generated Projects | `routes.py` lives in `infrastructure/entry_points/mcp_server/` and imports only the MCP SDK and Starlette. `app.py` (application layer) imports it, the same way it imports `tools`. No inward-crossing imports. | ✅ PASS |
+| II. Template-Driven Code Generation | New `routes.py.jinja2` and `test_routes.py.jinja2` live under `templates/entry_point/mcp/`, with rendering tests in `tests/templates/test_entry_point_templates.py`. They reuse the existing validated module context. | ✅ PASS |
+| III. Full Command Parity | No command, alias, or `--type` added or changed. | ✅ PASS |
+| IV. Python-First Idioms | The generated handler is `async`. `bind_routes` is fully typed (`-> None`). CLI changes are typed and keep ruff/mypy strict compliance. | ✅ PASS |
+| V. Test-First Development | Failing template, factory, and baseline tests are written before the templates and the factory edit. The generated project gets the `test_routes.py` scaffold. | ✅ PASS (enforced in `/speckit-tasks` → `/speckit-implement`) |
+| VI. Developer Experience | `--dry-run` previews both new files. No new error paths, so no new hints are needed. | ✅ PASS |
+| VII. Git Workflow and Branch Naming | Branch `feature/mcp-health-check` follows `feature/<kebab-name>`. | ✅ PASS |
+
+**Post-design re-check (after Phase 1)**: unchanged — all ✅. No violations; Complexity Tracking is empty.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/027-mcp-health-check/
+├── plan.md                    # This file
+├── research.md                # Phase 0
+├── data-model.md              # Phase 1
+├── quickstart.md              # Phase 1
+├── contracts/
+│   └── generated-routes.md    # Phase 1 — generated HTTP + file contract
+├── checklists/
+│   └── requirements.md        # From /speckit-specify + /speckit-clarify
+└── tasks.md                   # Phase 2 (/speckit-tasks — not created here)
+```
+
+### Source Code (repository root)
+
+```text
+src/scaffold_ca_python/
+├── factory/entry_points/
+│   └── ep_mcp.py                          # MODIFIED: always queue routes.py + test_routes.py; docstring updated
+└── templates/entry_point/mcp/
+    ├── routes.py.jinja2                   # NEW: bind_routes(mcp) + async health_check
+    ├── test_routes.py.jinja2              # NEW: GET 200 {"status":"ok"}, POST 405
+    ├── app.py.jinja2                      # MODIFIED: import routes; routes.bind_routes(mcp) after mcp creation
+    └── test_app.py.jinja2                 # MODIFIED: health route present once after repeated start_server(); GET through start_server() → 200
+
+tests/
+├── factory/
+│   ├── entry_points/test_ep_mcp.py        # MODIFIED: routes.py/test_routes.py queued (with and without optional flags)
+│   └── fixtures/dry_run_baseline.json     # MODIFIED: gep:mcp gains the two new paths
+└── templates/
+    └── test_entry_point_templates.py      # MODIFIED: render tests for routes/test_routes; app/test_app assertions
+```
+
+`CHANGELOG.md` is generated by release-please from the commit message (e.g. `feat(mcp): ...`), so it is not edited by hand.
+
+**Structure Decision**: Single-project CLI layout, the same as every prior feature. Changes stay inside `factory/entry_points/` and `templates/entry_point/mcp/` and their matching tests. `book_smcp/` is out of scope.
+
+## Complexity Tracking
+
+*No entries — Constitution Check reported no violations.*

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/quickstart.md

@@ -0,0 +1,65 @@
+# Quickstart: Validating the MCP Health Check Route
+
+**Feature**: `027-mcp-health-check`
+**Audience**: Developer implementing or reviewing this feature
+
+## Prerequisites
+
+- Python ≥ 3.13 and [uv](https://docs.astral.sh/uv/)
+- This repository on branch `feature/mcp-health-check`, with `uv sync` run once
+
+## 1. CLI test suite
+
+```bash
+uv run pytest tests/templates/test_entry_point_templates.py tests/factory/entry_points/test_ep_mcp.py tests/factory/test_dry_run_parity.py
+uv run pytest            # full suite, coverage gate ≥ 80%
+uv run ruff check . && uv run mypy src
+```
+
+Expected: everything passes. The dry-run baseline includes `routes.py` and `test_routes.py` under `gep:mcp`.
+
+## 2. Dry run in a throwaway project
+
+```bash
+cd /tmp
+uv run --project /path/to/scaffold-clean-architecture-py scaffold ca --name demo-mcp
+cd demo-mcp
+uv run --project /path/to/scaffold-clean-architecture-py scaffold gep --type mcp --dry-run
+```
+
+Expected: the preview lists `mcp_server/routes.py` and `mcp_server/test_routes.py`, and nothing is written (see [contract §5](./contracts/generated-routes.md#5-cli-dry-run-contract)).
+
+## 3. Generate and verify the generated project
+
+```bash
+uv run --project /path/to/scaffold-clean-architecture-py scaffold gep --type mcp
+uv sync
+uv run ruff check src
+uv run pytest
+```
+
+Expected:
+
+- `ruff` reports no issues for `routes.py` and `test_routes.py`.
+- `test_routes.py` and `test_app.py` pass without edits.
+
+## 4. Hit the endpoint
+
+```bash
+uv run demo-mcp &           # project script → server.main()
+curl -i http://localhost:8000/api/v1/health
+curl -i -X POST http://localhost:8000/api/v1/health
+kill %1
+```
+
+Expected:
+
+- `GET` returns `HTTP/1.1 200` with `{"status":"ok"}`.
+- `POST` returns `HTTP/1.1 405`.
+
+See [contract §1](./contracts/generated-routes.md#1-http-contract-generated-server).
+
+## 5. Regression checks
+
+- `scaffold gep --type mcp --with-resources --with-prompts` still generates `routes.py`, and the health check still answers.
+- `scaffold gep --type mcp --add-tool --name foo --returns str --description "x"` leaves `routes.py` and the `bind_routes` line in `app.py` untouched.

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/research.md

@@ -0,0 +1,63 @@
+# Research: MCP Entry Point Health Check Route
+
+**Feature**: `027-mcp-health-check` | **Date**: 2026-10-26
+
+No `NEEDS CLARIFICATION` items remained after `/speckit-clarify`. The research below records the technical decisions that the plan depends on.
+
+## R1 — How `FastMCP.custom_route` registers routes
+
+- **Decision**: Use `@mcp.custom_route(name="health_check", path="/api/v1/health", methods=["GET"])` inside `bind_routes(mcp)`.
+- **Rationale**: Verified in the installed SDK (`mcp/server/fastmcp/server.py`): `custom_route(path, methods, name=None, include_in_schema=True)` appends a Starlette `Route` to `self._custom_starlette_routes`, and `streamable_http_app()` copies that list into the Starlette app it builds (`routes.extend(self._custom_starlette_routes)`), after the `/mcp` route (lowest matching precedence). No new dependency is needed.
+- **Alternatives considered**: Adding a separate Starlette `Route` next to the `Mount("/")` in `start_server()` — rejected because it moves route wiring into the composition root and bypasses the `bind_*` pattern already used by `tools`, `resources`, and `prompts`.
+
+## R2 — When to call `bind_routes(mcp)`
+
+- **Decision**: Call `routes.bind_routes(mcp)` once at module level in `app.py`, immediately after `mcp: FastMCP = FastMCP(...)` (clarification Q2).
+- **Rationale**:
+  - `streamable_http_app()` takes a snapshot of the custom routes when `start_server()` runs. Tools, resources, and prompts are bound later, inside `lifespan`, so binding the health route there would leave it out of the route table.
+  - `custom_route` does not deduplicate. A module-level call happens once per process, so repeated `start_server()` calls in `test_app.py` do not accumulate duplicate routes.
+- **Alternatives considered**: Inside `start_server()` (works in production, duplicates routes in tests); inside `lifespan` (route never registered).
+
+## R3 — `bind_routes` is synchronous
+
+- **Decision**: `def bind_routes(mcp: FastMCP) -> None` (not `async`), without `@inject`.
+- **Rationale**: It runs at import time, outside an event loop, and has no dependencies to inject. Only the handler `health_check` is `async`, which satisfies Principle IV (async I/O in generated code).
+- **Alternatives considered**: `async def bind_routes` awaited from `lifespan` for symmetry with `bind_tools` — rejected by R2.
+
+## R4 — Lint compliance of the generated `routes.py`
+
+- **Decision**: Render the reference code with minimal fixes: module docstring, `from __future__ import annotations`, sorted imports (`JSONResponse, Response`), two blank lines before `def`, and `-> None` on `bind_routes` (clarification Q1).
+- **Rationale**: Generated projects run `ruff` with `select = ["E", "F", "I", "UP", "ANN"]`. The raw reference fails `I001` (unsorted imports) and `ANN201` (missing return type). `from __future__ import annotations` is safe here because neither `custom_route` nor Starlette's `Route` inspects handler annotations.
+- **Alternatives considered**: `noqa` comments or per-file ignores — rejected; they add noise to generated code.
+
+## R5 — How the generated tests exercise the route
+
+- **Decision**: `test_routes.py` builds a fresh `FastMCP("test")`, calls `bind_routes(mcp)`, wraps `mcp.streamable_http_app()` in `starlette.testclient.TestClient` (used **without** a `with` block, so the MCP session-manager lifespan is not started), and asserts:
+  - `GET /api/v1/health` returns 200 with body `{"status": "ok"}`.
+  - `POST /api/v1/health` returns 405.
+- **Rationale**:
+  - `TestClient` needs `httpx`, which `mcp` already declares (`Requires-Dist: httpx>=0.27.1`). The generated pyproject already filters httpx deprecation warnings, so no new test dependency is needed.
+  - A fresh `FastMCP` per test avoids touching the module-level instance in `app.py`.
+  - Starlette answers 405 when the path matches but the method does not. It also adds `HEAD` automatically for `GET` routes.
+- **Alternatives considered**: Building a bare `Starlette(routes=mcp._custom_starlette_routes)` — rejected because it relies on a private attribute.
+
+## R6 — How `test_app.py` asserts single registration
+
+- **Decision**: Call `start_server()` twice, then assert that `/api/v1/health` appears exactly once among the routes of the mounted app (`server.routes[0].routes`, i.e. `Mount.routes`, which proxies to the inner Starlette app).
+- **Rationale**: Locks in FR-008 and the clarification Q2 guarantee using only public Starlette APIs.
+
+## R7 — CLI-side test and fixture impact
+
+- **Decision**:
+  - Add `routes.py` and `test_routes.py` to the `gep:mcp` entry in `tests/factory/fixtures/dry_run_baseline.json`.
+  - Add a factory test in `tests/factory/entry_points/test_ep_mcp.py`.
+  - Add template rendering tests in `tests/templates/test_entry_point_templates.py`, covering the new templates plus the `app.py`/`test_app.py` changes.
+- **Rationale**:
+  - The dry-run parity test compares sorted queued paths against the baseline.
+  - Principle II requires rendering tests per template group, and `entry_point/mcp/` is already covered in that file.
+- **Alternatives considered**: None.
+
+## R8 — SDK version drift
+
+- **Decision**: Keep the `mcp~=1.30.0` pin; no change.
+- **Rationale**: `custom_route` and `streamable_http_app` exist with the same signatures in the 1.x line (verified against an installed 1.27.0; the 1.30 pin targets the same FastMCP API, as noted in `ep_mcp.py`).

scaffold_ca_python-0.5.0/specs/027-mcp-health-check/spec.md

@@ -0,0 +1,147 @@
+# Feature Specification: MCP Entry Point Health Check Route
+
+**Feature Branch**: `feature/mcp-health-check`
+
+**Created**: 2026-10-26
+
+**Status**: Draft
+
+**Input**: User description: "When the `mcp` entry point is generated, also generate a health endpoint in a module named `routes.py` inside `infrastructure/entry_points/mcp_server/`, exposing a `GET /api/v1/health` health check that returns `{\"status\": \"ok\"}` via a `bind_routes(mcp)` function."
+
+## Clarifications
+
+### Session 2026-10-26
+
+- Q: Should the generated `routes.py` follow the reference code exactly, or be adjusted so it passes the generated project's lint rules? → A: Keep the reference behavior and structure, with minimal lint fixes (`-> None` on `bind_routes`, sorted imports, module docstring, `from __future__ import annotations`, matching `tools.py`).
+- Q: Where in the generated `app.py` should `routes.bind_routes(mcp)` be called: once at module level right after `mcp` is created, or inside `start_server()`? → A: At module level, immediately after `mcp` is created; registered exactly once per process.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Generated MCP server exposes a health check out of the box (Priority: P1)
+
+A developer generates an MCP entry point (`scaffold-ca-python gep --type mcp`) in a Clean Architecture project. Without writing any extra code, the resulting server answers a health check request so it can be deployed behind load balancers, container orchestrators (liveness/readiness probes), and uptime monitors.
+
+**Why this priority**: A health endpoint is a baseline operational requirement for any deployable service. Without it, every team must hand-write the same route before the server can run in a managed environment.
+
+**Independent Test**: Run `gep --type mcp --dry-run` and confirm `routes.py` is listed; render `routes.py` and confirm `bind_routes` registers `GET /api/v1/health` returning `{"status": "ok"}` on a standalone `FastMCP` instance. (Reaching the endpoint on the running server additionally requires User Story 2.)
+
+**Acceptance Scenarios**:
+
+1. **Given** a freshly scaffolded project, **When** the developer runs `gep --type mcp`, **Then** a `routes.py` module is created at `src/<pkg>/infrastructure/entry_points/mcp_server/routes.py` alongside `tools.py`.
+2. **Given** the generated `routes.py`, **When** the developer inspects it, **Then** it exposes a single public function `bind_routes(mcp)` that registers a route named `health_check` at path `/api/v1/health` registered for `GET`.
+3. **Given** the generated MCP server is running, **When** a client sends `GET /api/v1/health`, **Then** the server responds with HTTP 200, a JSON content type, and the body `{"status": "ok"}`.
+4. **Given** the generated MCP server is running, **When** a client sends any method other than `GET` or `HEAD` (e.g. `POST`) to `/api/v1/health`, **Then** the server rejects it with HTTP 405.
+
+---
+
+### User Story 2 - Health route is wired into the composition root automatically (Priority: P1)
+
+The developer does not have to edit the application composition root to activate the health route; the generated `app.py` already binds it so the endpoint is live as soon as the server starts.
+
+**Why this priority**: A generated route that is not wired is dead code. Wiring is part of the same deliverable as Story 1 and is required for its acceptance scenario 3 to pass.
+
+**Independent Test**: Render the generated `app.py`, build the ASGI application with `start_server()`, and confirm the `/api/v1/health` route is present in the application's route table before any request or lifespan event runs.
+
+**Acceptance Scenarios**:
+
+1. **Given** the generated `application/app.py`, **When** the developer inspects it, **Then** it imports `routes` from the `mcp_server` package and calls `routes.bind_routes(mcp)`.
+2. **Given** the generated application, **When** `start_server()` builds the ASGI app, **Then** the health route is already registered (it is bound at module import time, not inside `start_server()` or the lifespan).
+3. **Given** the generated application, **When** `start_server()` is called multiple times in the same process (e.g. across tests), **Then** `/api/v1/health` appears exactly once in the route table.
+4. **Given** the generated application with resources and/or prompts enabled, **When** the server starts, **Then** the health route is still registered and the existing tools/resources/prompts behaviour is unchanged.
+
+---
+
+### User Story 3 - Generated project ships a test for the health route (Priority: P2)
+
+The generated project includes a test file for `routes.py` so the health contract is covered from day one and TDD remains the default workflow.
+
+**Why this priority**: Required by the constitution (Principle V: every `generate-*` command MUST produce a corresponding test scaffold), but the server is still operable without it.
+
+**Independent Test**: Generate a project with the `mcp` entry point and run its test suite; the routes test passes without modification.
+
+**Acceptance Scenarios**:
+
+1. **Given** `gep --type mcp` was run, **When** the developer lists the tests, **Then** `tests/infrastructure/entry_points/mcp_server/test_routes.py` exists (resolved through the project's tests root).
+2. **Given** the generated test, **When** it runs, **Then** it asserts that `GET /api/v1/health` returns 200 with body `{"status": "ok"}`.
+
+---
+
+### Edge Cases
+
+- **Dry run**: `gep --type mcp --dry-run` MUST list `routes.py` and `test_routes.py` in the preview and write nothing to disk.
+- **Existing MCP entry point**: If `mcp_server/` already exists, `gep --type mcp` aborts with the existing "Directory already exists" error before writing `routes.py` (no new policy is introduced).
+- **Conflicting entry point**: When the `restapi` entry point is already present, the existing MCP/restapi conflict check still aborts generation before `routes.py` is written.
+- **Optional primitives**: The health route is generated regardless of `--with-resources` / `--with-prompts`; it is not gated by any flag.
+- **`gep --type mcp --add-tool`**: Adding tools afterwards MUST NOT modify or remove `routes.py` or its binding in `app.py`.
+- **Route ordering**: The health route MUST NOT be shadowed by the MCP HTTP app mounted at `/`.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The `mcp` entry-point generator MUST always emit `src/<pkg>/infrastructure/entry_points/mcp_server/routes.py`, independent of optional flags.
+- **FR-002**: `routes.py` MUST be rendered from a new Jinja2 template under the existing `entry_point/mcp/` template group (no string assembly), per Principle II.
+- **FR-003**: `routes.py` MUST expose a synchronous public function `bind_routes(mcp)` that receives the server's `FastMCP` instance and registers the health route on it.
+- **FR-004**: The health route MUST be named `health_check`, served at `/api/v1/health`, accept `GET` (Starlette implicitly also answers `HEAD` for `GET` routes), and be implemented as an `async` handler (Principle IV: async-first in generated code).
+- **FR-005**: The health route MUST respond with HTTP 200 and the JSON body `{"status": "ok"}`, with no dependency on the DI container, domain, or driven adapters.
+- **FR-006**: The generated `application/app.py` MUST import `routes` and call `routes.bind_routes(mcp)` once at module level, immediately after the `mcp` instance is created, so the route is registered exactly once per process and before `start_server()` builds the ASGI application. `start_server()` MUST NOT register routes, and `routes` is not added to `container.wire(...)`.
+- **FR-007**: The generator MUST emit `tests/infrastructure/entry_points/mcp_server/test_routes.py` (via the resolved tests root) covering the 200/`{"status": "ok"}` contract and the 405 response for `POST`.
+- **FR-008**: The generated `test_app.py` MUST assert that the `/api/v1/health` route is present exactly once in the application returned by `start_server()`, and that `GET /api/v1/health` against that application returns 200 with `{"status": "ok"}`.
+- **FR-009**: The generated `routes.py` and `test_routes.py` MUST pass the generated project's `ruff` lint configuration.
+- **FR-010**: The generated `routes.py` MUST only import from the MCP SDK and Starlette (already declared dependencies); no new runtime dependency is added.
+- **FR-011**: `--dry-run` output for `gep --type mcp` MUST include both new files, and the dry-run parity baseline MUST be updated accordingly.
+- **FR-012**: The CLI test suite MUST include template rendering tests for `routes.py.jinja2` and `test_routes.py.jinja2` under `tests/templates/`, plus factory tests asserting the files are queued by the `mcp` entry-point factory.
+- **FR-013**: The generated `routes.py` MUST keep the behavior and structure of the requester's reference code, adjusted only as needed to satisfy FR-009 (`ruff` rules `E`, `F`, `I`, `UP`, `ANN`) and to match the conventions of `tools.py`. Expected output:
+
+  ```python
+  """MCP custom routes binding — register non-MCP HTTP routes such as the health check."""
+
+  from __future__ import annotations
+
+  from mcp.server.fastmcp import FastMCP
+  from starlette.requests import Request
+  from starlette.responses import JSONResponse, Response
+
+
+  def bind_routes(mcp: FastMCP) -> None:
+      """
+      Bind routes to the FastMCP instance.
+      """
+
+      @mcp.custom_route(name="health_check", path="/api/v1/health", methods=["GET"])
+      async def health_check(_request: Request) -> Response:
+          """
+          Health check endpoint to verify the server is running.
+
+          Returns:
+              JSON response indicating the server is healthy.
+          """
+
+          response_data = {"status": "ok"}
+          return JSONResponse(response_data)
+  ```
+
+### Key Entities
+
+- **Health response**: A minimal payload with a single field `status` whose value is `"ok"` when the server process is up and able to serve HTTP requests.
+- **Route binder (`bind_routes`)**: The single extension point for non-MCP HTTP routes of the generated server; future custom routes are added inside it.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of projects generated with `gep --type mcp` contain `routes.py` and `test_routes.py`, verified by the CLI factory tests.
+- **SC-002**: A freshly generated MCP project answers `GET /api/v1/health` with `{"status": "ok"}` with zero manual edits by the developer.
+- **SC-003**: The generated project's test suite passes on first run, including the new routes test.
+- **SC-004**: The CLI test suite keeps its ≥ 80% coverage gate and all existing MCP entry-point tests still pass unchanged (other than the intended dry-run baseline update).
+
+## Assumptions
+
+- The health check is a **liveness** signal only: it reports that the process is serving HTTP and does not probe downstream dependencies (databases, external APIs). Readiness checks are out of scope.
+- The health route is public (no authentication), consistent with standard probe usage.
+- The path `/api/v1/health` is fixed; making it configurable via settings is out of scope.
+- The health route is served by the same host/port as the MCP server (existing `HOST`/`PORT` settings); no separate listener is introduced.
+- Only the `mcp` entry point is affected; `restapi`, `agent`, and `generic` entry points are unchanged.
+- Existing projects that already generated the MCP entry point are not migrated. Re-running `gep --type mcp` is blocked by the existing `mcp_server/` directory guard, so those projects must add `routes.py` and the `routes.bind_routes(mcp)` line in `app.py` manually.
+- Only `ruff` compliance is required for generated files; `mypy --strict` compliance of the generated project is out of scope (`FastMCP.custom_route` is an untyped decorator).
+- The reference `book_smcp/` sample project is not part of this feature's scope.