fix: pin mcp<2 (package uninstallable since 2026-07-28) + v0.5.1 + English tutorial - #5
Merged
Conversation
added 3 commits
August 22, 2026 18:21
The MCP Python SDK shipped 2.0.0 on 2026-07-28, which removes the `mcp.server.fastmcp` module (`mcp/server/` now carries auth, lowlevel, mcpserver). `server/app.py` imports `FastMCP` from that path, and the dependency was declared as an unbounded `mcp>=1.0.0` — so every fresh `pip install topicforge` resolved to 2.0.0 and produced a server that raised ImportError on startup. Verified against the real artifacts: `mcp-2.0.0-py3-none-any.whl` contains zero `fastmcp` entries; with the `<2` bound pip resolves to `mcp-1.29.0`, which still ships `mcp/server/fastmcp/__init__.py` exporting `FastMCP`. The break was masked twice over: the dev environment already had `mcp 1.27.1` installed, and the last CI run predates the SDK release, so both the local suite and the green badge kept passing against a version nobody installs any more. Bumps to 0.5.1 and cuts the accumulated external-audit work (Lots 0-5, 2026-07-08) out of [Unreleased]. The Cyclone `take_iter` -> `read_iter` change in that batch is still validated by static analysis only and ships with that caveat recorded in the changelog — an uninstallable package harms every user, while that change can only reach users running the Cyclone backend against a live bus. Migrating to the 2.x API (FastMCP -> MCPServer, transport options moved to .run(), stateless protocol) is deliberately out of scope here. Claude-Session: https://claude.ai/code/session_01Us8nLW5XexX1N28nb3dgUp
…ntract New `docs/TUTORIEL.md` (French filename, English content, per maintainer preference): quickstart on the mock adapter, the eleven-tool table, advanced options, five copy-pasteable scheduled-task prompts, and a Privacy section. Every fact was verified against the code rather than the surrounding docs, since tool-count and feature-status drift is a known recurring problem in this repo: - the five mock fixture topics named in the quickstart - the tool parameters used in the prompts (count, window_seconds, lookback_seconds, domain_id) and the TopicMetrics field names (frequency_hz_observed / _declared, sequence_gaps_count) - the DDS defaults (backend `mock`, domain id 0, range 0..232) - the telemetry contract: six fields, not the five its class docstring claims, and the two tests that pin OFF-means-no-network Two corrections worth noting. The per-call `domain_id` parameter does not override `TOPICFORGE_DDS_DOMAIN_ID` — the Cyclone/Fast adapters join one domain at construction and accept the parameter for protocol uniformity only, so the doc says to restart instead. And the metrics prompt calls `peek_dds_samples` before `topic_metrics` because the metrics buffer only fills opportunistically on peeks; without that first call the tool returns zeros. The `[dds-opendds]` and `[dds-dust]` extras are documented as failing at install time rather than presented as available. Claude-Session: https://claude.ai/code/session_01Us8nLW5XexX1N28nb3dgUp
…ollection The Windows Task Scheduler instructions pointed at `C:\Users\Yanis\Documents\TopicForge`, a path that does not exist — the repo lives under `Documents\Projects\TopicForge`. This is why the traction folder holds exactly one snapshot, dated 2026-05-14, and why the "weekly" collection documented here has produced nothing in the 100 days since: a task created by following these instructions would have failed on every run. (No such task currently exists on the machine either, so the collection was never operational at all — it ran once by hand while this README was being written.) Correcting the path is a prerequisite for the decision gates in product-plan.md §12 to ever have data to evaluate. Claude-Session: https://claude.ai/code/session_01Us8nLW5XexX1N28nb3dgUp
There was a problem hiding this comment.
🟢 Approval recommended
The dependency pin and version bump directly address the reported install break and the remaining feedback is a minor changelog formatting nit.
Pull request overview
This PR ships an urgent hotfix release to restore installability after the MCP Python SDK 2.0.0 removal of mcp.server.fastmcp, by bounding the mcp dependency to <2, and publishes a v0.5.1 release with updated documentation and changelog entries.
Changes:
- Pin runtime dependency to
mcp>=1.0.0,<2and bump package version to0.5.1. - Add a new English tutorial (
docs/TUTORIEL.md) covering quickstart, tool surface, advanced options, scheduled prompts, and privacy/telemetry. - Fix the documented Windows Task Scheduler working directory for traction snapshot collection.
File summaries
| File | Description |
|---|---|
src/topicforge/__init__.py |
Bumps library __version__ to 0.5.1. |
pyproject.toml |
Bumps package version and pins mcp to <2 to prevent broken fresh installs. |
docs/TUTORIEL.md |
Adds an English tutorial for setup, tools, operations, and privacy. |
docs/projet-file/traction/README.md |
Corrects the Task Scheduler path so scheduled traction snapshots run in the right repo directory. |
CHANGELOG.md |
Adds a 0.5.1 release section documenting the MCP pin and associated scope note; updates compare links. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| ## [0.5.1] - 2026-08-22 | ||
|
|
||
| ### Fixed |
Cutting the accumulated audit work into 0.5.1 left the release with two `### Fixed` subsections — the hotfix entry and the Lot 2/3 entries. Duplicate headings under one version break changelog parsers and read ambiguously. Qualifies the hotfix one, matching the convention the surrounding sections already use (`### Added (Lot 4 — test hardening)`, `### Changed (Lot 5 — DDS adapter deduplication)`). The audit-authored heading is left untouched. Raised by the Copilot review on PR #5. Claude-Session: https://claude.ai/code/session_01Us8nLW5XexX1N28nb3dgUp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why this is urgent
pip install topicforgehas produced a non-starting server since 2026-07-28.The MCP Python SDK released
2.0.0that day, alongside the2026-07-28protocol revision. That release removes themcp.server.fastmcpmodule —mcp/server/now shipsauth,lowlevel, andmcpserver.server/app.py:12doesfrom mcp.server.fastmcp import FastMCP, and the dependency was declared as an unboundedmcp>=1.0.0, so a fresh resolve picks2.0.0and the import fails.Verified against the real artifacts rather than inferred:
fastmcpentries inmcp-2.0.0-py3-none-any.whlpip download "mcp>=1.0.0"resolves to2.0.0(broken)pip download "mcp>=1.0.0,<2"resolves to1.29.0mcp/server/fastmcp/__init__.pyin 1.29.0, exportsFastMCPThe break was masked twice: the dev environment already had
mcp 1.27.1installed, and the last CI run predates the SDK release — so both the local suite and the green badge kept passing against a version nobody installs any more. PyPI recorded 9 downloads in the affected window.What is in here
fix(deps)— pinmcp>=1.0.0,<2, bump to0.5.1, cut the accumulated external-audit work (Lots 0–5, 2026-07-08) out of[Unreleased].docs— newdocs/TUTORIEL.md: English tutorial with a mock-mode quickstart, the eleven-tool table, advanced options, five copy-pasteable scheduled-task prompts, and a Privacy section documenting the six-field telemetry contract.docs(traction)— correct the Task Scheduler path that made weekly traction collection fail silently since May.Scope caveat, recorded deliberately
This release ships the Cyclone
take_iter→read_iterchange, which is still validated by static analysis only (ruff+py_compile) and has not been exercised against a real multi-vendor DDS bus. It ships because an uninstallable package harms every user, while that change can only reach users running the Cyclone backend against a live bus. The caveat is recorded in the changelog. Real-bus validation remains open.Migrating to the 2.x SDK API (
FastMCP→MCPServer, transport options moved to.run(), stateless protocol) is not in this PR.Verification
python -m ruff check src tests→ All checks passedpython -m pytest→ 484 passed, 24 skipped (unchanged from baseline)Follow-up this exposes
Nothing detected this for 25 days because no CI job installs dependencies fresh. A scheduled job resolving the dependency tree against current PyPI would have caught it within a week.
https://claude.ai/code/session_01Us8nLW5XexX1N28nb3dgUp