feat: add MCP documentation page and modernize server#4152
Merged
MarkusNeusinger merged 2 commits intomainfrom Jan 28, 2026
Merged
feat: add MCP documentation page and modernize server#4152MarkusNeusinger merged 2 commits intomainfrom
MarkusNeusinger merged 2 commits intomainfrom
Conversation
- Add new MCP documentation page with details on configuration and available tools - Update protocol description in existing documentation to reflect Streamable HTTP - Remove references to deprecated SSE transport in code and documentation
Use FASTMCP_STATELESS_HTTP env var instead of constructor parameter to avoid deprecation warning in FastMCP >= 2.x. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request adds comprehensive MCP documentation to the website and modernizes the MCP server implementation by removing the deprecated SSE transport. The changes span both frontend and backend components, with additional improvements to ESLint configuration and React component structure.
Changes:
- Adds a new
/mcppage with comprehensive documentation about MCP integration, configuration, available tools, use cases, and resources - Removes deprecated SSE transport from the MCP server, keeping only modern Streamable HTTP
- Fixes FastMCP stateless_http deprecation warning by using environment variable approach
- Adds ESLint configuration for the React frontend with TypeScript support
- Extracts context hooks from Layout component to dedicated hooks file to fix React Fast Refresh warnings
- Fixes ESLint exhaustive-deps warnings in FilterBar and SpecTabs components
- Reorders footer links for symmetrical layout
- Updates planning command templates to include completion verification step
Reviewed changes
Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| specs/260128-remove-sse-mcp-transport.md | Spec document for SSE removal chore |
| docs/reference/plausible.md | Adds /mcp page to analytics documentation |
| docs/reference/mcp.md | Updates protocol from "JSON-RPC over SSE" to "Streamable HTTP" |
| app/yarn.lock | Adds ESLint and TypeScript ESLint dependencies |
| app/src/router.tsx | Adds McpPage route at /mcp |
| app/src/pages/McpPage.tsx | New comprehensive MCP documentation page |
| app/src/pages/SpecPage.tsx | Updates useAppData import to use hooks |
| app/src/pages/HomePage.tsx | Updates context hook imports |
| app/src/pages/CatalogPage.tsx | Updates context hook imports |
| app/src/hooks/useLayoutContext.ts | New file with extracted context hooks and types |
| app/src/hooks/useFilterState.ts | Updates useHomeState import |
| app/src/hooks/index.ts | Exports new layout context hooks |
| app/src/components/SpecTabs.tsx | Adds specId to handleCopy dependency array |
| app/src/components/Layout.tsx | Imports context from hooks instead of defining locally |
| app/src/components/Footer.tsx | Reorders links and adds mcp link |
| app/src/components/FilterBar.tsx | Fixes exhaustive-deps warnings by adding missing dependencies |
| app/package.json | Adds ESLint packages and updates lint script |
| app/eslint.config.js | New ESLint configuration with TypeScript and React support |
| api/mcp/server.py | Uses environment variable for stateless HTTP mode |
| api/main.py | Removes SSE app creation and mount point |
| .claude/commands/*.md | Adds serena think command to templates |
Comment on lines
+81
to
+82
| // Allow ref updates during render (common pattern for keeping refs in sync) | ||
| 'react-hooks/refs': 'off', |
There was a problem hiding this comment.
The rule 'react-hooks/refs' on line 82 does not exist in eslint-plugin-react-hooks. The plugin only provides two rules: 'react-hooks/rules-of-hooks' and 'react-hooks/exhaustive-deps'. This rule should be removed or corrected to a valid rule name. If the intent was to disable exhaustive-deps warnings for ref updates, that should be handled differently (e.g., by using eslint-disable comments where needed or adjusting the exhaustive-deps configuration).
Suggested change
| // Allow ref updates during render (common pattern for keeping refs in sync) | |
| 'react-hooks/refs': 'off', |
Comment on lines
+1
to
+80
| # Chore: Remove SSE MCP Transport | ||
|
|
||
| ## Chore Description | ||
| Remove the deprecated SSE (Server-Sent Events) transport from the MCP server and keep only the modern Streamable HTTP transport. SSE was the old MCP standard before SDK 1.0, but all actively maintained MCP clients (Claude Desktop, Claude Code, Cursor, Cline, MCP Inspector) now support Streamable HTTP. Removing SSE simplifies the codebase: | ||
| - Single MCP app instead of two | ||
| - One endpoint to document (`/mcp` only) | ||
| - Simpler lifespan management | ||
| - Less code to maintain and test | ||
|
|
||
| The `stateless_http=True` fix has already been applied to `api/mcp/server.py`. | ||
|
|
||
| ## Relevant Files | ||
| Use these files to resolve the chore: | ||
|
|
||
| - **`api/main.py`** - Contains MCP app creation, lifespan management, and route mounting. Need to remove `mcp_sse_app` creation, its lifespan context, and the `/sse` mount. | ||
| - **`api/mcp/server.py`** - MCP server definition. Already has `stateless_http=True` fix applied. No changes needed. | ||
| - **`app/src/pages/McpPage.tsx`** - Frontend MCP documentation page. Need to remove SSE endpoint row from the table. | ||
| - **`docs/reference/mcp.md`** - Full MCP documentation. Need to update protocol description from "JSON-RPC over SSE" to "Streamable HTTP". | ||
|
|
||
| ### New Files | ||
| None required. | ||
|
|
||
| ## Step by Step Tasks | ||
| IMPORTANT: Execute every step in order, top to bottom. | ||
|
|
||
| ### Step 1: Remove SSE from api/main.py | ||
| - Remove the `mcp_sse_app` creation line (line ~50): | ||
| ```python | ||
| # Remove this line: | ||
| mcp_sse_app = mcp_server.http_app(path="/", transport="sse") | ||
| ``` | ||
| - Update the lifespan function to remove nested SSE context: | ||
| ```python | ||
| # Change from: | ||
| async with mcp_http_app.lifespan(app): | ||
| async with mcp_sse_app.lifespan(app): | ||
| logger.info("MCP server initialized (HTTP + SSE)") | ||
| yield | ||
|
|
||
| # To: | ||
| async with mcp_http_app.lifespan(app): | ||
| logger.info("MCP server initialized") | ||
| yield | ||
| ``` | ||
| - Remove the SSE mount (line ~142): | ||
| ```python | ||
| # Remove this line: | ||
| app.mount("/sse", mcp_sse_app) # SSE transport at /sse | ||
| ``` | ||
| - Update the comment above mcp_http_app to remove SSE mention | ||
|
|
||
| ### Step 2: Update McpPage.tsx frontend | ||
| - Remove the SSE row from the endpoints table in the "What is MCP" section | ||
| - Keep only the Streamable HTTP row | ||
| - The table should show only: | ||
| ``` | ||
| Streamable HTTP | https://api.pyplots.ai/mcp | ||
| ``` | ||
|
|
||
| ### Step 3: Update docs/reference/mcp.md | ||
| - Update the protocol description in the "MCP vs REST API" table: | ||
| - Change `| **Protocol** | JSON-RPC over SSE | HTTP/JSON |` | ||
| - To: `| **Protocol** | Streamable HTTP | HTTP/JSON |` | ||
|
|
||
| ### Step 4: Run Validation Commands | ||
| Execute all validation commands to ensure zero regressions. | ||
|
|
||
| ## Validation Commands | ||
| Execute every command to validate the chore is complete with zero regressions. | ||
|
|
||
| - `uv run ruff check api/ && uv run ruff format api/` - Lint and format backend code | ||
| - `uv run pytest tests/unit/api/mcp/` - Run MCP unit tests | ||
| - `cd app && yarn lint` - Lint frontend code | ||
| - `cd app && yarn build` - Build frontend to verify TypeScript compiles | ||
|
|
||
| ## Notes | ||
| - The `stateless_http=True` change in `api/mcp/server.py` was already applied in an earlier commit and should remain. | ||
| - After this change, only `/mcp` endpoint will be available for MCP clients. | ||
| - The MCP Inspector command in the documentation (`npx @modelcontextprotocol/inspector https://api.pyplots.ai/mcp`) remains valid. | ||
| - This change needs to be deployed to production for the fix to take effect on `api.pyplots.ai`. |
There was a problem hiding this comment.
The README.md still contains references to the deprecated SSE transport endpoint that is being removed in this PR. The "SSE Transport" configuration section should be removed, and only the "Streamable HTTP Transport" configuration should remain. Additionally, the transport should no longer be labeled as "modern, bidirectional" since it will be the only option.
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.
Summary
/mcppage with comprehensive MCP documentation (What is MCP, Configuration, Available Tools, Use Cases, Resources)Test plan
/mcpendpoint🤖 Generated with Claude Code