This document records what was found and done while migrating epr-mcp from
FastMCP 2.x and httpx to FastMCP 4 and httpx2, rewriting the tutorials and
demos, and fixing what running against a real EPR exposed. It was filled in
phase by phase; the plan it followed is
fastmcp4_httpx2_migration_implementation_plan.md.
| Area | Result |
|---|---|
| Dependencies | fastmcp>=4.0,<5, httpx2>=2.13, pydantic>=2.12, starlette>=1.0; legacy httpx is gone |
| Server | create_server(cfg) plus run(cfg); stdio and http transports; flat tool arguments; nine tools verified against a live EPR |
| Packaging | py3-none-any wheel that includes openapi.yaml; SPDX license metadata; Dockerfile installs the wheel by glob |
| Workshop | Eight modules, four checkpoints, an EPR-only compose file, a preflight, and a terminal client |
| Demos | Three demos, three presenter scripts, and run_all.sh |
| Quality | 316 tests pass (2 functional tests skipped by default and passing when enabled), 94% coverage, 41 doctests, ruff clean, all markdown lint-clean |
The release is version 2.0.0 because behavior changes (see the 2.0 notes in the README); the version bump itself is a post-merge step (see the release checklist).
| Path | Role |
|---|---|
src/epr_mcp/server.py |
create_server, run, the nine tools, and the HTTP routes |
src/epr_mcp/common.py |
create_client: the httpx2 client with the optional bearer token, and the GraphQL helpers |
src/epr_mcp/config.py |
Config with url, token, debug, transport, host, port |
src/epr_mcp/main.py |
The eprmcp command: --transport, --host, --port, token and URL |
src/epr_mcp/schemas.py |
Input and response validation (unknown fields rejected) |
docs/tutorials/ |
The workshop and its code, EPR compose file, and preflight |
demos/ |
Demos, presenter scripts, and scripts/run_all.sh |
tests/ |
Unit, tutorial, demo, and functional tests |
The details follow, by phase: what the research found (Phase 0), the httpx2 swap (Phase 1), the FastMCP 4 changes, flat arguments, and packaging (Phase 2), the workshop and the real-EPR fixes (Phase 3), the demos (Phase 4), and the documentation and release work (Phase 5).
Research date: 2026-10-06. Method: read the upstream docs, then installed
fastmcp 4.0.11 and the pre-migration set into scratch virtualenvs outside the
repo and exercised the current code against them. No repository code changed in
this phase.
Environment: Python 3.12.11, fastmcp 2.12.4, httpx 0.28.1.
| Check | Result |
|---|---|
ruff check src/ |
2 errors, 1 auto-fixable (import ordering in server.py); not clean |
pytest |
126 passed, 0 failed |
Coverage over src/ |
40% total; server.py 5%, schemas.py 64%; below the 80% gate in AGENTS.md |
Committed wheel in dist/ |
Contains no openapi.yaml (see Findings, item 6) |
| Topic | Finding |
|---|---|
| Python requirement | fastmcp requires Python >= 3.10; the project's >= 3.12 stays valid |
| Installed dependency versions | httpx2 2.13.1, httpcore2 2.13.1, mcp 2.3.0, pydantic 2.13.5, starlette 1.7.0, truststore 0.10.4 |
Legacy httpx |
Not installed alongside FastMCP 4; any leftover import httpx raises ModuleNotFoundError, so the swap is checkable |
FastMCP(...) constructor |
Second positional parameter is instructions; version is keyword-only |
Context logging |
debug, info, warning, error, log exist and are awaitable |
custom_route |
Present, same shape (path, methods) |
run / run_async |
Same signature: transport, show_banner, **transport_kwargs; transport="http", host=, port= works |
fastmcp.server.openapi |
Removed; fastmcp.server.providers.openapi provides OpenAPIProvider, RouteMap, MCPType (moot, module is deleted) |
| In-memory test client | Client(server_instance) works; mode defaults to "auto"; Client also accepts Path, URL, and transport objects |
| stdio transport | mcp.run(transport="stdio") works; a StdioTransport(command, args) client lists and calls tools |
| httpx2 API | httpx2.MockTransport exists; default User-Agent is python-httpx2/2.13.1 |
A copy of src/ with openapi_server.py removed and import httpx replaced by
import httpx2 as httpx was run against FastMCP 4.0.11:
server.run(cfg)constructs the server; all 9 tools register with unchanged decorators andAnnotated[..., Field(...)]parameters.- An in-memory
Clientlists the 9 tools and callsfetch_event; with EPR unreachable the tool returns the expected "Connection failed" message, so thehttpx2.ConnectErrorbranch inhandle_http_errorsworks through the swap. - Starlette
TestClientreturns 200 for/health,/openapi.yaml,/openapi.json, and/docs.
Conclusion: the migration is mostly mechanical; the risks are in the items below.
versionbug confirmed. The running server reportsinstructions="1.0.0"andversion="4.0.11". Fix with keyword arguments (Phase 2).- Client logging is deprecated. Every
ctx.debugandctx.errorcall emits anMCPDeprecationWarningstating that the logging capability is deprecated as of 2026-07-28 (SEP-2577). Decision needed in Phase 2: move diagnostics to Pythonlogging(stderr, already configured inmain.py) and keepctxlogging out of the tool bodies, which also reduces noise over stdio. - Default HTTP bind.
run()binds0.0.0.0:8000regardless ofMCP_HOSTandMCP_PORT; unchanged by FastMCP 4, handled in Phase 2. - Lint baseline is not clean. Fix the 2 existing
rufferrors in Phase 1 so later phases can rely on the gate. - Coverage baseline is 40%.
server.pyneeds the Phase 2 in-memory-client tests to reach the 80% gate. - Packaging bug. The wheel built from the current
pyproject.tomldoes not includeopenapi.yaml, so/openapi.yamland/openapi.jsonwould return 404 in the Docker image. Add package data (and a test that the file is found) in Phase 2. - Build backend.
build-backend = "setuptools.build_meta:__legacy__"and thepy2.py3universal wheel tag are stale; reconsider in Phase 2 together with the Dockerfile wheel glob.
| Dependency | Constraint to set in pyproject.toml |
|---|---|
| Python | >= 3.12 (unchanged) |
fastmcp |
>= 4.0, < 5 |
httpx2 |
>= 2.13 |
pydantic |
>= 2.12 |
starlette |
>= 1.0 (FastMCP 4 resolves 1.7.0) |
httpx |
Removed |
uv runlaunching the stdio server from VS Code and Claude Desktop (the stdio transport itself is verified). Confirmed in Phase 3 on macOS and Linux.- Whether
fastmcp4 emits a deprecation warning for themcp.run(...)call styles the tutorials will teach; check while writing module 01.
pyproject.toml:fastmcp>=4.0,<5,httpx2>=2.13,pydantic>=2.12,starlette>=1.0;httpxremoved; toxextrasfixed totest.src/epr_mcp/server.py:import httpx2; the exception checks inhandle_http_errorsusehttpx2types; the 9 client sites usecreate_client(cfg).src/epr_mcp/common.py: newcreate_client(cfg)returning anhttpx2.AsyncClientwith a JSON content type and an optional bearer header.src/epr_mcp/config.py:Config.tokenis optional (defaultNone); it was typedstrbut is passedNonewhen no token is set.src/epr_mcp/openapi_server.py: deleted (decision); it imported the removedfastmcp.server.openapiand the legacyhttpx.tests/unit/test_http_errors.py: new tests forhandle_http_errors(connect, timeout, status, generic errors) and a guard against legacyhttpximports.tests/unit/test_common.py: newTestCreateClientcovering the bearer header, no header without a token, and the client type.
The two baseline ruff errors are fixed.
- The EPR token is now sent as
Authorization: Beareron every request made byserver.py. Before,server.pynever sent it. - The User-Agent becomes
python-httpx2/<version>. - TLS verification uses the operating system trust store instead of the bundled
certificertificates;SSL_CERT_FILEandSSL_CERT_DIRare still honored. - The three POST search tools no longer set their own
Content-Typeheader; the shared client sets it.
ruff check src/ tests/ passes, 134 tests pass (126 before), and no legacy
httpx import remains in src/ or tests/. Coverage is 43% (was 40%);
server.py coverage arrives with the Phase 2 in-memory-client tests.
src/epr_mcp/server.py:run(cfg)is split intocreate_server(cfg)(builds theFastMCPinstance with all tools and routes, binds nothing) andrun(cfg)(picks the transport and starts it).FastMCP(name="EPR MCP Server", version="1.0.0")uses keyword arguments; the server previously reported"1.0.0"as its instructions.- All
ctx.debugandctx.errorcalls are nowlogger.debugandlogger.error, and the unusedctx: Contextparameters are removed from the tools.handle_http_errors(e, operation, cfg)is a plain function. runsupportsstdio(banner off, so nothing but protocol traffic is written to stdout) andhttpwith the configured host and port, usingmcp.run(...)instead ofasyncio.run(mcp.run_async(...)). It rejects any other transport withValueError, and no longer logs the token (it logs only whether one is configured).
src/epr_mcp/config.py:Configgainstransport,host, andport;TRANSPORTSlists the valid transports.src/epr_mcp/main.py: new--transport,--host, and--portoptions withMCP_TRANSPORT,MCP_HOST, andMCP_PORTas defaults. The token is read fromEPR_API_TOKENorEPR_TOKEN.pyproject.toml:openapi.yamlis package data; the build backend is the standardsetuptools.build_meta; theuniversalwheel setting is removed so the wheel is taggedpy3-none-any;pytest-asyncioandpytest-covare in the test extra and tox deps.Dockerfile: installsdist/epr_mcp-*-py3-none-any.whlinstead of a hard-coded0.1.0file name.Makefile:make wheelremovesbuild/anddist/first, because a stalebuild/libpreviously leaked deleted modules into the wheel.
- New
--transport stdio|http,--host, and--portoptions and matching environment variables. Defaults match the old behavior (http,0.0.0.0,8000). EPR_TOKEN, whichdocker-compose.yamland.env.exampleset, now reaches the server. Before, onlyEPR_API_TOKENwas read, so the token never arrived in Docker.- Tool diagnostics go to the server log, not to MCP client log notifications.
/openapi.yamland/openapi.jsonwork from the installed wheel; the old wheel omitted the spec.
203 tests pass and 2 functional tests are skipped by default; coverage is 87%
(server.py 82%, up from 5%). New files:
tests/unit/test_server_tools.py: in-memoryClientagainstcreate_server, with EPR replaced byhttpx2.MockTransport; covers tool registration and schemas, success, empty, non-2xx, validation failure, connect error, and timeout for all 9 tools, plus the bearer header.tests/unit/test_server_routes.py: the four HTTP routes through the StarletteTestClient, and a check that the spec ships as package data.tests/unit/test_server_run.py: transport selection, host and port, token not logged, debug flag.tests/unit/test_main.py: command line and environment handling.tests/functional/test_transports.py: starts the real process over stdio and over HTTP and lists the tools. Run withEPR_MCP_FUNCTIONAL=1; both pass.
A wheel built from a clean copy of the tree contains openapi.yaml and no
openapi_server.py. The image built from it reports healthy, serves
/health, /openapi.yaml, and /openapi.json with 200, lists 9 tools over
HTTP through a FastMCP 4 client, returns the "Connection failed" message with no
EPR running, and has no legacy httpx installed.
- A
fetch_eventcall against a running EPR,docker compose up, and the MCP Inspector. They need a running EPR, which Phase 3 sets up; they remain part of the Phase 2 success criteria until then. uv runlaunching the stdio server from VS Code (Phase 3).
The search and create tools used to require their argument wrapped one level
deeper (search_events took {"data": {"data": {"name": ...}}}, create_event
took {"event_data": {"data": {...}}}), although the tool descriptions implied
flat input, so a normal MCP client got "Field required". This is fixed:
server.pyadds thedatawrapper internally beforevalidate_input, so tools take flat input:search_eventstakes{"data": {"name": "foo"}}andcreate_eventtakes{"event_data": {...fields...}}. The tool parameter names and the JSON schemas are unchanged.- The six search and create input models in
schemas.pynow forbid unknown keys. Without this, a caller still using the old wrapped shape would have its criteria silently dropped and run an unfiltered search that returns every record. It now gets an input validation error and no request is sent. - The
search_groupsdescription no longer mentions anenabledcriterion, which the model never supported; sending it is now rejected. - Tests: all tool tests use flat input; new
TestFlatArgumentscovers the rejection of the old wrapped shape and of unknown criteria for every search and create tool, andtest_schemas.pycovers the unknown-key rejection. Totals: 215 tests pass, 2 functional tests skipped by default, coverage 88%.
This is a breaking change for any client that sent the old wrapped shape; list it in the 2.0 notes.
schemas.py calls raise ValidationError("...") with the Pydantic class, which
cannot be constructed that way; those branches would fail with a TypeError
instead of a validation message.
docs/tutorials/: the six hyphenated tutorials (which taught the officialmcpSDK,pip install mcp[cli] httpx, and Docker-launched stdio) are replaced byREADME.md(agenda, prerequisites, checkpoint table, facilitator notes) and eight lowercase modules:00_intro,01_first_tool,02_inspector,03_complete_tool_set,04_validation_and_errors,05_test_it,06_use_from_an_editor, and07_misc_and_troubleshooting.docs/tutorials/code/:pyproject.tomlanduv.lockpinningfastmcp4.0.11 andhttpx22.13.1; four checkpoint directories;docker-compose.yamlandepr/Dockerfilefor EPR only;seed_epr.py;check_setup.py(preflight);client.py(terminal MCP client);.vscode/mcp.jsonandclaude_desktop_config.jsonfor two servers, the workshop server and the shippedeprmcp, both launched withuv runover stdio.tests/tutorials/test_tutorial_code.py: every checkpoint server imports and lists the right tools, the checkpoint 05 tests pass, checkpoint 05's server equals checkpoint 04's, both editor configs reference existing files, the compose file runs only EPR services, file names follow AGENTS.md Rule 1, and no stalemcp.server.fastmcp,import httpx, or FastMCP 2 references remain outside module 07.Makefile: newworkshop-checktarget..gitignore:work/,seed_ids.json, and the saved EPR image are ignored, and the tutorial's.vscode/is re-included (.vscodeis ignored repository-wide).pyproject.toml:testpaths = ["tests"]so a plainpytestdoes not collect the tutorial code.
- Checkpoints hold the finished code at the end of a module (the starter for a module is the previous checkpoint) instead of separate starter and solution directories. There is no checkpoint 02 or 06 because those modules do not change code.
- The workshop server is a standalone file, not a copy of the shipped package.
Module 04 uses
ToolErrorfor failures; the shipped server returns error text. - The plan's dry run with a person new to the project has not happened, so the timings in the agenda are estimates.
EPR was built and started with the workshop compose file, then the seed script, the tutorial servers, and the shipped server were run against it. This found problems that mocked tests could not:
- EPR's own image does not start. Its Dockerfile builds
FROM scratchwith no time zone database, and the server always connects to Postgres withTimeZone=America/New_York, so it exits with "unknown time zone". The workshopepr/Dockerfilebuilds the same pinned commit (f8f115b790c58b8fab3bfd47278e51e4f15e9f0e) and adds/usr/share/zoneinfo. There is no published EPR image; the first build takes about three minutes. - The shipped create tools reported failure on success. EPR answers a
create with HTTP 200, but the shipped tools only accepted 201, so every
create_*call returned "Failed to create..." although the record was created. They now accept 200 and 201. - The shipped create tools failed after a successful create. EPR returns
only the new ID (
{"data": "<id>"}), but the tools tried to validate it as a record. They now return{"message": "... created successfully", "id": "<id>"}when EPR returns an ID, and still handle a full record. create_receivercould not work. EPR requires aschema("invalid input: schema is required"), and the input model had noschemafield (after the Phase 2 change to forbid unknown keys, supplying one was rejected too). The model now requiresschema, accepted under that name.search_groupsalways returned an empty list. It asked for afingerprintfield that the EPR GraphQL typeEventReceiverGroupdoes not have, the query failed, and the error was swallowed. The field is removed, and all three search tools now report a GraphQLerrorslist instead of hiding it.- Error shapes differ by case. A well-formed missing ID is HTTP 404; a
malformed ID or a bad GraphQL query is HTTP 200 with
{"data": null, "errors": [...]}. The tutorial server checks for both. A stopped EPR behind Docker's port proxy surfaces asReadErrorwith an empty message rather thanConnectError, so the tutorial mapsTransportErrorand shows the exception name. - The Inspector is now version 2.9.0 with a different interface and an access token in the URL. Module 02 pins that version and describes only the steps that hold across versions.
Unit tests were added for items 2 to 5 (TestAgainstRealEprBehavior and
TestCreateReturnsIdOnly in tests/unit/test_server_tools.py); the suite is
238 tests passing with 88% coverage.
- On macOS: the full preflight (
check_setup.py) passes, including starting the workshop server and the shipped server with the exactuv runcommands from the editor configs and listing 9 tools each; every command in modules 00 to 05 was run against the live EPR;uv run pytest workanduv run pytest checkpoint_05_testspass. - On Linux (a
uvDocker image with Python 3.12 and uv 0.9.30): the same preflight passes against the macOS-hosted EPR. - The Phase 2 items that needed a running EPR are now checked: all nine shipped tools work against the live EPR, over stdio and over HTTP.
- The VS Code and Claude Desktop screens and the Inspector 2.9.0 interface were not opened. Modules 02 and 06 describe the steps from the documentation and the launch commands are tested, but the on-screen wording is unconfirmed.
- No dry run of the agenda with a new attendee, so timings are estimates.
demos/generate_epr_events.py: moved tohttpx2; theuliddependency is gone (the script now builds ULIDs itself: a 48-bit millisecond timestamp plus 80 random bits in Crockford base32, covered by tests); the release string usedstrftime("%Y.%m.%s"), where%sis the epoch seconds on some platforms and unsupported on others, and is now%d; the script exits 1 when any request fails; thehttpx2request log is quiet so the demo output is readable.demos/openapi_demo.py: rewritten. The old script was broken (it inserted a non-existentdemos/srconsys.path, imported unused modules, and only printed a hard-coded tool list). The new one starts the server over HTTP on a free port (or uses--url), calls/health,/openapi.yaml,/openapi.json, and/docs, checks that the YAML and JSON agree, and lists the tools through a FastMCP 4 client. It needs no EPR.demos/mcp_client_demo.py: new. A FastMCP 4 client lists the tools, creates a receiver and an event, fetches the event, searches for it, and shows a malformed ID being rejected. It starts the server over stdio, or uses--server-urlfor HTTP.demos/scripts/: presenter scriptsgenerate_events_script.md,openapi_demo_script.md, andmcp_client_demo_script.md(goal, prerequisites, commands, expected output, talking points, failure recovery, reset) andrun_all.sh, an unattended rehearsal run that checks prerequisites, stops at the first failure, and supports--skip-generate.demos/requirements.txtlistsfastmcp,httpx2, andPyYAML(it listedhttpxandulid, while the README saidulid-py, and the script calledulid.ulid()).demos/README.mdis rewritten: it had an OpenAPI tool list offetchEvent-style names that the server never had, an MCP client example that used a non-existent API, and said the generator posts 33 events when it posts 44.Makefilelintand the toxcheckandformatenvironments now includedemos/;.gitignoreignoresepr_reports/, which--write-to-diskcreates.tests/demos/test_demos.py: ULID format and ordering, the 11 receivers and 44 events, the dry run (55 curl commands, exit 0), an unreachable EPR (exit 1),--write-to-disk, the OpenAPI demo end to end, the client demo helpers, no legacyhttpximport,run_all.shsyntax and option handling, and that every demo has a presenter script and a README entry.
- The 255 tests pass (2 skipped by default) at 88% coverage, and
ruff check src tests demos docs/tutorials/codeis clean. - Against the live EPR on macOS: the generator posts 11 receivers and 44 events
(exit 0); the client demo passes over stdio and over HTTP; the OpenAPI demo
passes;
demos/scripts/run_all.shexits 0, and exits 1 with a clear message when EPR is unreachable. - On Linux (the
uvDocker image):run_all.sh --skip-generateexits 0 against the same EPR.
- The shipped tools report most problems (validation, EPR unreachable) as plain
text instead of an MCP error result, so the client demo treats a reply that is
not JSON as a failure. The workshop server (module 04) uses
ToolError; the shipped server could be changed to match in a later release. src/epr_mcp/openapi.yaml, which the server serves, calls the service the "Event Processing Registry" (it is the Event Provenance Registry) and lists/searchand/healthpaths that the real EPR does not have; its search is GraphQL. The presenter script tells the presenter not to promise that every listed path exists. Correcting the document is outside this migration.- The generator does not post its events to groups, and
--write-to-diskwrites to the current directory.
- Root
README.mdrewritten. The old one described tools that do not exist (fetchEventand friends "generated from the OpenAPI specification",healthCheck), amcp.call_toolAPI, Docker-launched editor configurations, and a/healthcheck against EPR; it now covers install and run, both transports, the options and environment table, the nine tools with their flat arguments, the HTTP endpoints, editor configuration, Docker, development, an "Upgrading to 2.0" section, and troubleshooting. - Recreated under AGENTS.md Rule 1 names, written fresh against the current code
rather than copied (the old text described removed code and used emojis):
docs/README.md,docs/how-tos/docker_compose.md,docs/reference/openapi_implementation.md, anddocs/reference/schema_validation.md.docs/docker_reference.mdanddocs/troubleshooting.mdstay deleted, as decided; the README and workshop module 07 hold the troubleshooting material. .env.example: documentsMCP_TRANSPORT,MCP_HOST, andMCP_PORT, and says that Compose fixes the container to0.0.0.0:8000overhttp, so they do not change a Compose deployment.docker-compose.yaml:EPR_TOKEN=${EPR_TOKEN:-}so an unset token no longer prints a warning..dockerignoreadded so the build context excludes.git,.venv,tests,docs, anddemos.pyproject.toml: the license is now the SPDX expressionApache-2.0withlicense-files, the deprecated license classifier is gone, and setuptools>=77is required. The build had warned thatproject.licenseas a table stops being supported on 2027-02-18.- Docstrings were added to 15 public functions and classes that lacked them; the completeness audit below finished the job for every public item.
make wheelin a clean copy builds without warnings; the wheel containsopenapi.yamland the license, and its metadata lists the new requirements.- The Docker image built from that wheel through
docker compose buildstarts, reportshealthy, serves/healthand/openapi.yaml, and logsTransport: httpandEPR Token configured: TruewhenEPR_TOKENis set. - Every relative link in the repository's markdown resolves.
- A search finds no
mcp.server.fastmcp, legacyhttpximport, FastMCP 2 reference, all-caps documentation name, orulid-pyoutside this directory, the tutorial's migration notes, and the guard tests that name them. make testsruns tox, which creates fresh environments and downloads packages; it was not run. The same checks were run directly (see below).
| Suite | Covers |
|---|---|
tests/unit/test_server_tools.py |
All nine tools through an in-memory client with a mocked EPR, including the real-EPR behaviors |
tests/unit/test_server_routes.py, test_server_run.py, test_main.py |
HTTP routes, transport selection, command line and environment |
tests/unit/test_schemas.py, test_common.py, test_http_errors.py |
Validation, the client factory, httpx2 error handling |
tests/tutorials/test_tutorial_code.py |
Every workshop checkpoint, configs, naming, and stale references |
tests/demos/test_demos.py |
The three demos and run_all.sh |
tests/functional/test_transports.py |
The real process over stdio and over HTTP (EPR_MCP_FUNCTIONAL=1) |
Final gate, run from the repository root:
ruff check src/ tests/ demos/ docs/tutorials/code
ruff format --check src/ tests/ demos/ docs/tutorials/code
pytest --cov=src --cov-report=term-missing --cov-fail-under=80
EPR_MCP_FUNCTIONAL=1 pytest tests/functional
pytest --doctest-modules --import-mode=importlib src/epr_mcp
markdownlint --config .markdownlint.json <changed files>
prettier --check --parser markdown --prose-wrap always <changed files>Start the server for an editor, or as a service:
uv run eprmcp start --transport stdio --url http://localhost:8042
uv run eprmcp start --transport http --host 127.0.0.1 --port 8000Call a tool with flat arguments from Python:
async with Client("http://127.0.0.1:8000/mcp") as client:
await client.call_tool("search_events", {"data": {"name": "checkout-service"}})Rehearse the demos against a live EPR:
(cd docs/tutorials/code && docker compose up -d --build)
demos/scripts/run_all.shAfter Phase 5 the plan was checked item by item against the repository and AGENTS.md. Five audit agents were started, but all hit the session rate limit and returned nothing, so the audit was done directly. Everything below was found and fixed in that pass, and verified by running the gates.
| Finding | Fix |
|---|---|
Rule 3: 46 functions in src/epr_mcp lacked Args, Returns, or Examples (including the nine tools and four routes) |
Every public function now has all three sections; 33 examples run as doctests |
| Rule 3: the demos, workshop scripts, and checkpoint servers had one-line or no docstrings | Full docstrings throughout; 8 more doctests in the demos; checkpoints 04 and 05 stay identical |
| Rule 3: test modules, fixtures, helpers, and classes had no docstrings | Added to every test, fixture, helper, and test class |
| Copyright: the new test files had no SPDX header | Added to every new test file |
Rule 4: Popen used without a context manager in a demo and a functional test |
running_server context manager in the OpenAPI demo; with subprocess.Popen in the test |
Rule 5: public functions with no direct test (Config.as_dict, seed_epr, check_setup, client.py, the demo helpers) |
New test_config.py, test_tutorial_scripts.py, and test_demo_helpers.py |
| Plan 2.4: "for each tool test connect error, timeout, non-200, response validation failure" was only covered for some tools | A matrix over all nine tools (TestEveryToolHandlesEprFailures) |
| Plan 3.2: "CI-check that every solution imports and passes its tests" had a test but no CI | .github/workflows/ci.yaml runs ruff, the tests with the 80% floor, doctests, and the markdown gates; it has not run on GitHub yet |
| YAML lint warnings in the files created for the migration | Document start markers added |
Still not done, because it cannot be done from the command line:
- The VS Code, Claude Desktop, and Inspector 2.9.0 screens, and the dry run of the workshop with a new attendee (plan items 3.4 and 3.5; one deliverable box stays unticked on purpose).
make tests(tox, which downloads packages); the same checks were run directly.- The first run of the new CI workflow.
The version stays 0.1.0 in the pull request. After it merges, the maintainer:
- Bumps the version to
2.0.0inpyproject.toml(constants.pyreads it from the installed package metadata, so no second edit is needed). - Runs the quality gate above once more on the merge commit.
- Runs
make wheeland checksdist/epr_mcp-2.0.0-py3-none-any.whl: it should containepr_mcp/openapi.yamland noopenapi_server.py. - Runs
make docker-image, then starts the image and checks/health. - Updates the version in
docs/tutorials/code/.vscode/mcp.jsonexamples only if they pin one (they do not today) and tagsv2.0.0. - Publishes with
make release(the toxreleaseenvironment uploads to the package index) and pushes the image to the registry in use. - Announces the breaking changes using the "Upgrading to 2.0" section of the README.
Known follow-ups that are outside this migration:
src/epr_mcp/openapi.yamlcalls EPR the "Event Processing Registry" and lists paths the real EPR does not have.- The tools return errors as text rather than as MCP error results; the workshop
server shows the
ToolErroralternative. - The Prometheus and Grafana profiles in
docker-compose.yamlexpect/metricsand provisioning files that do not exist. schemas.pyraisespydantic.ValidationErrordirectly in a few validators, which cannot be constructed that way.- The workshop agenda has not been dry-run with a new attendee, and the VS Code, Claude Desktop, and Inspector 2.9.0 screens have not been opened.