Replace Claude for Desktop with VS Code + Copilot in server quickstart#2139
Draft
jonathanhefner wants to merge 12 commits intomodelcontextprotocol:mainfrom
Draft
Replace Claude for Desktop with VS Code + Copilot in server quickstart#2139jonathanhefner wants to merge 12 commits intomodelcontextprotocol:mainfrom
jonathanhefner wants to merge 12 commits intomodelcontextprotocol:mainfrom
Conversation
The new script is a superset of the old one. It continues to handle the existing `<!-- snippet-source -->` markers in `README.v2.md`, and adds support for syncing code snippets into Python docstrings and markdown docs under `docs/`. New capabilities beyond the old script: - Region extraction from example files using `# region` / `# endregion` markers, so a single example file can provide multiple snippets - All source paths resolve relative to the repository root - Scans `src/**/*.py` and `docs/**/*.md` in addition to the README - Caches file contents and extracted regions for efficiency The marker format uses HTML comments (`<!-- snippet-source -->` / `<!-- /snippet-source -->`), which are invisible when rendered by `mkdocstrings` and do not interfere with `pymdownx.superfences` code fence parsing.
Add support for `<!-- snippet-source #region_name -->` markers that omit the companion file path. The path is derived from the target file's location using the mapping `src/X` → `examples/snippets/docstrings/X`. This eliminates line-length violations on marker lines in docstrings, since the full companion path no longer needs to be embedded in every marker. The full-path form continues to work for non-`src/` targets like markdown files.
Move inline code examples from docstrings in `src/mcp/` into standalone companion files at `examples/snippets/docstrings/mcp/`, mirroring the source tree structure. The `scripts/sync_snippets.py` script keeps the docstring content in sync with the companion files via `<!-- snippet-source #RegionName -->` markers. This ensures all docstring examples are checked by pyright and ruff, catching type errors and style drift that would otherwise go unnoticed in raw docstring text. The pattern follows the TypeScript SDK's approach of one companion file per source file, with each example in a named function whose parameters supply typed context. 19 companion files cover 42 code examples across the public API surface: `MCPServer`, `Client`, `ClientSession`, `Context`, `ResponseRouter`, `ServerTaskContext`, `ExperimentalTaskHandlers`, `ClientCredentialsOAuthProvider`, `PrivateKeyJWTOAuthProvider`, `SignedJWTParameters`, and others. All source markers use path-less form (`#RegionName`) — the companion path is derived automatically from the target file location. Region names follow `ClassName_methodName_variant` without abbreviation. Pyright execution environment for the companion files suppresses only "unused artifact" diagnostics inherent to example code (`reportUnusedFunction`, `reportUnusedVariable`, `reportAbstractUsage`, `reportUnusedClass`, `reportPrivateUsage`). All actual type-checking rules remain enabled.
Add a "Docstring Code Examples" section covering the companion file system: directory layout, `<!-- snippet-source #RegionName -->` markers, `ClassName_methodName_variant` naming, the function-parameter pattern for typed dependencies, and the prohibition on type-suppression comments inside regions.
`sync_snippets.py` also syncs snippet-source markers in `docs/**/*.md` and `README.v2.md`, not just `src/` docstrings. Add a short section after "Docstring Code Examples" noting that these files use explicit paths (path-less `#Region` markers are only supported in `src/` files).
The previous documentation had two flat sections where the docstring section contained all the detail and the markdown section referred to it vaguely. Reorganize into a `## Code Snippet System` intro covering shared concepts (marker format, region extraction, naming conventions, function wrappers, typed params, `# type: ignore` prohibition, pyright workflow) with `### Markdown Code Examples` and `### Docstring Code Examples` subsections covering only what is unique to each target type.
The links to snippet source files are redundant since the code blocks already contain the entire source. Removes all 33 occurrences.
Import the quickstart MCP client from `modelcontextprotocol/quickstart-resources` into `examples/clients/quickstart-client/`. This is the companion code for the "Building MCP clients" tutorial at modelcontextprotocol.io. The client connects to any MCP server via stdio, discovers its tools, and runs an interactive chat loop where user queries are sent to Claude with the server's tools available for use. Changes from the upstream source: - Moved `import sys` to top-level imports - Added return type annotations (`-> None`) to all methods - Added `assert self.session is not None` guards for type narrowing - Changed `tool.inputSchema` to `tool.input_schema` (SDK Python name) - Added proper Anthropic type annotations (`MessageParam`, `ToolParam`, `TextBlock`, `ToolUseBlock`, `ToolResultBlockParam`, `TextBlockParam`) - Fixed tool result handling to use proper `ToolResultBlockParam` with `tool_use_id` linkage and explicit MCP `TextContent` to Anthropic `TextBlockParam` conversion, replacing the original code which passed raw MCP content objects to the Anthropic API Root `pyproject.toml` adds `mcp-quickstart-client` as a dev dependency with a workspace source mapping. This is necessary because `anthropic` is a new external dependency not already in the root package's transitive dependency tree, and without this, `uv sync --all-extras` (used by CI) would not install it, causing `pyright` to fail.
Convert the "Building MCP clients" tutorial from modelcontextprotocol.io (Mintlify MDX) into a Diataxis-style tutorial for the Python SDK docs. Code blocks are synced from `examples/clients/quickstart-client/client.py` via `<!-- snippet-source -->` markers and `# region` tags, so the tutorial stays in sync with the actual example code that gets type-checked. Changes to the tutorial content (vs the original Mintlify source): - Strip all Mintlify JSX (`<Tabs>`, `<CodeGroup>`, `<Warning>`, etc.) and convert to MkDocs Material syntax (`===` tabs, `!!! admonitions`) - Remove non-tutorial sections per Diataxis: "Key Components Explained", "Common Customization Points", "Best Practices" - Merge "System Requirements" and API key setup into a single "Prerequisites" section; show API key inline in run commands - Use sentence case for headings throughout - Tailor troubleshooting errors to real Python exceptions Changes to the example at `examples/clients/quickstart-client/`: - Add `# region` / `# endregion` markers for 5 snippet regions - Remove `python-dotenv` dependency, `load_dotenv()`, and `.env.example` (API key is now passed inline via environment variable) - Update `README.md` link to point to the new tutorial
Import the weather server from the external `quickstart-resources` repo into `examples/servers/quickstart-server/`, adapting it for the monorepo. The layout uses a top-level `weather.py` script with a stub `mcp_quickstart_server/` package for hatchling, keeping the code faithful to what the tutorial guide shows readers. Changes from the original: - `FastMCP` → `MCPServer` (renamed in the SDK) - `mcp[cli]` → plain `mcp` (CLI extras not needed at runtime) - Bare `dict` → `dict[str, Any]` for type safety - Added `list[str]` annotation and `-> None` return type for pyright
Convert the "Building MCP servers" tutorial from modelcontextprotocol.io into a MkDocs-compatible markdown guide. Code blocks are wired up to `examples/servers/quickstart-server/weather.py` via `<!-- snippet-source -->` markers so the tutorial stays in sync with the type-checked example. Conversion from the Mintlify source: - Replace JSX components (`<Note>`, `<Warning>`, `<CodeGroup>`, `<AccordionGroup>`, `<CardGroup>`, etc.) with MkDocs equivalents (`!!! note`, `!!! warning`, `=== "Tab"` tabs, `???` collapsible sections, bullet lists) - Remove `<Frame>`/`<img>` tags (images are Mintlify-hosted assets) - Strip the `<Tabs><Tab title='Python'>` wrapper (Python-only SDK) - Update internal Mintlify links to full `modelcontextprotocol.io` URLs or relative doc links - Update `FastMCP` references to `MCPServer` to match the example code Content improvements over the Mintlify source: - Rename "Implementing tool execution" to "Registering tools" with prose describing the `@mcp.tool()` decorator API - Replace standalone logging section with a concise `!!! important` admonition after the "Running the server" code block - Drop misleading "Run `uv run weather.py`" instruction (stdio transport hangs without a client) - Use collapsible `???` sections for troubleshooting - Fix debugging guide links to `/legacy/tools/debugging` - Drop SDK version prerequisite (redundant — `uv add` installs latest) - Replace `mcp[cli]` with plain `mcp` (CLI extras not needed at runtime) Also adds `# region` / `# endregion` markers to `weather.py` for the four snippet regions, and adds the new page to `mkdocs.yml` nav.
Claude for Desktop is not available on Linux, making it a stumbling block for the server quickstart. Replace the testing instructions with VS Code + GitHub Copilot, which works on all platforms and is free to use. - Replace `claude_desktop_config.json` setup with `.vscode/mcp.json` - Replace Claude Desktop troubleshooting with VS Code-specific guidance - Generalize "under the hood" section to say "LLM" instead of "Claude" - Update intro references This aligns the Python SDK quickstart with the TypeScript SDK, which made the same change in modelcontextprotocol/typescript-sdk#1557.
jonathanhefner
force-pushed
the
server-quickstart-use-vs-code
branch
from
7d36279 to
057078e
Compare
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
1 participant
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.
ℹ️ This is based on top of #2138.
Claude for Desktop is not available on Linux, making it a stumbling block for the server quickstart. Replace the testing instructions with VS Code + GitHub Copilot, which works on all platforms and is free to use.
claude_desktop_config.jsonsetup with.vscode/mcp.jsonThis aligns the Python SDK quickstart with the TypeScript SDK, which made the same change in modelcontextprotocol/typescript-sdk#1557.