Merge branch 'main' into v1.2.x

Author: dsp-ant

Diff for: CLAUDE.md

@@ -0,0 +1,73 @@
+# Tool Usage Learnings
+
+This file is intended to be used by an LLM such as Claude.
+
+## UV Package Manager
+
+- Use `uv run` to run Python tools without activating virtual environments
+- For formatting: `uv run ruff format .`
+- For type checking: `uv run pyright`
+- For upgrading packages:
+  - `uv add --dev package --upgrade-package package` to upgrade a specific package
+  - Don't use `@latest` syntax - it doesn't work
+  - Be careful with `uv pip install` as it may downgrade packages
+
+## Git and GitHub CLI
+
+- When using gh CLI for PRs, always quote title and body:
+  ```bash
+  gh pr create --title "\"my title\"" --body "\"my body\""
+  ```
+- For git commits, use double quotes and escape inner quotes:
+  ```bash
+  git commit -am "\"fix: my commit message\""
+  ```
+
+## Python Tools
+
+### Ruff
+- Handles both formatting and linting
+- For formatting: `uv run ruff format .`
+- For checking: `uv run ruff check .`
+- For auto-fixing: `uv run ruff check . --fix`
+- Common issues:
+  - Line length (default 88 chars)
+  - Import sorting (I001 errors)
+  - Unused imports
+- When line length errors occur:
+  - For strings, use parentheses and line continuation
+  - For function calls, use multiple lines with proper indentation
+  - For imports, split into multiple lines
+
+### Pyright
+- Type checker
+- Run with: `uv run pyright`
+- Version warnings can be ignored if type checking passes
+- Common issues:
+  - Optional types need explicit None checks
+  - String operations need type narrowing
+
+## Pre-commit Hooks
+
+- Configuration in `.pre-commit-config.yaml`
+- Runs automatically on git commit
+- Includes:
+  - Prettier for YAML/JSON formatting
+  - Ruff for Python formatting and linting
+- When updating ruff version:
+  - Check available versions on PyPI
+  - Update `rev` in config to match available version
+  - Add and commit config changes before other changes
+
+## Best Practices
+
+1. Always check git status and diff before committing
+2. Run formatters before type checkers
+3. When fixing CI:
+   - Start with formatting issues
+   - Then fix type errors
+   - Then address any remaining linting issues
+4. For type errors:
+   - Get full context around error lines
+   - Consider optional types
+   - Add type narrowing checks when needed

Diff for: examples/fastmcp/unicode_example.py

@@ -0,0 +1,64 @@
+"""
+Example FastMCP server that uses Unicode characters in various places to help test
+Unicode handling in tools and inspectors.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP()
+
+
+@mcp.tool(
+    description="🌟 A tool that uses various Unicode characters in its description: "
+    "á é í ó ú ñ 漢字 🎉"
+)
+def hello_unicode(name: str = "世界", greeting: str = "¡Hola") -> str:
+    """
+    A simple tool that demonstrates Unicode handling in:
+    - Tool description (emojis, accents, CJK characters)
+    - Parameter defaults (CJK characters)
+    - Return values (Spanish punctuation, emojis)
+    """
+    return f"{greeting}, {name}! 👋"
+
+
+@mcp.tool(description="🎨 Tool that returns a list of emoji categories")
+def list_emoji_categories() -> list[str]:
+    """Returns a list of emoji categories with emoji examples."""
+    return [
+        "😀 Smileys & Emotion",
+        "👋 People & Body",
+        "🐶 Animals & Nature",
+        "🍎 Food & Drink",
+        "⚽ Activities",
+        "🌍 Travel & Places",
+        "💡 Objects",
+        "❤️ Symbols",
+        "🚩 Flags",
+    ]
+
+
+@mcp.tool(description="🔤 Tool that returns text in different scripts")
+def multilingual_hello() -> str:
+    """Returns hello in different scripts and writing systems."""
+    return "\n".join(
+        [
+            "English: Hello!",
+            "Spanish: ¡Hola!",
+            "French: Bonjour!",
+            "German: Grüß Gott!",
+            "Russian: Привет!",
+            "Greek: Γεια σας!",
+            "Hebrew: !שָׁלוֹם",
+            "Arabic: !مرحبا",
+            "Hindi: नमस्ते!",
+            "Chinese: 你好!",
+            "Japanese: こんにちは!",
+            "Korean: 안녕하세요!",
+            "Thai: สวัสดี!",
+        ]
+    )
+
+
+if __name__ == "__main__":
+    mcp.run()

Diff for: examples/servers/simple-prompt/mcp_simple_prompt/server.py

@@ -90,9 +90,9 @@ async def get_prompt(
     if transport == "sse":
         from mcp.server.sse import SseServerTransport
         from starlette.applications import Starlette
-        from starlette.routing import Route
+        from starlette.routing import Mount, Route
 
-        sse = SseServerTransport("/messages")
+        sse = SseServerTransport("/messages/")
 
         async def handle_sse(request):
             async with sse.connect_sse(
@@ -102,14 +102,11 @@ async def handle_sse(request):
                     streams[0], streams[1], app.create_initialization_options()
                 )
 
-        async def handle_messages(request):
-            await sse.handle_post_message(request.scope, request.receive, request._send)
-
         starlette_app = Starlette(
             debug=True,
             routes=[
                 Route("/sse", endpoint=handle_sse),
-                Route("/messages", endpoint=handle_messages, methods=["POST"]),
+                Mount("/messages/", app=sse.handle_post_message),
             ],
         )
 

Diff for: examples/servers/simple-resource/mcp_simple_resource/server.py

@@ -47,9 +47,9 @@ async def read_resource(uri: AnyUrl) -> str | bytes:
     if transport == "sse":
         from mcp.server.sse import SseServerTransport
         from starlette.applications import Starlette
-        from starlette.routing import Route
+        from starlette.routing import Mount, Route
 
-        sse = SseServerTransport("/messages")
+        sse = SseServerTransport("/messages/")
 
         async def handle_sse(request):
             async with sse.connect_sse(
@@ -59,14 +59,11 @@ async def handle_sse(request):
                     streams[0], streams[1], app.create_initialization_options()
                 )
 
-        async def handle_messages(request):
-            await sse.handle_post_message(request.scope, request.receive, request._send)
-
         starlette_app = Starlette(
             debug=True,
             routes=[
                 Route("/sse", endpoint=handle_sse),
-                Route("/messages", endpoint=handle_messages, methods=["POST"]),
+                Mount("/messages/", app=sse.handle_post_message),
             ],
         )
 

Diff for: examples/servers/simple-tool/mcp_simple_tool/server.py

@@ -60,9 +60,9 @@ async def list_tools() -> list[types.Tool]:
     if transport == "sse":
         from mcp.server.sse import SseServerTransport
         from starlette.applications import Starlette
-        from starlette.routing import Route
+        from starlette.routing import Mount, Route
 
-        sse = SseServerTransport("/messages")
+        sse = SseServerTransport("/messages/")
 
         async def handle_sse(request):
             async with sse.connect_sse(
@@ -72,14 +72,11 @@ async def handle_sse(request):
                     streams[0], streams[1], app.create_initialization_options()
                 )
 
-        async def handle_messages(request):
-            await sse.handle_post_message(request.scope, request.receive, request._send)
-
         starlette_app = Starlette(
             debug=True,
             routes=[
                 Route("/sse", endpoint=handle_sse),
-                Route("/messages", endpoint=handle_messages, methods=["POST"]),
+                Mount("/messages/", app=sse.handle_post_message),
             ],
         )
 

Diff for: pyproject.toml

@@ -42,9 +42,9 @@ mcp = "mcp.cli:app [cli]"
 [tool.uv]
 resolution = "lowest-direct"
 dev-dependencies = [
-    "pyright>=1.1.378",
-    "pytest>=8.3.3",
-    "ruff>=0.8.1",
+    "pyright>=1.1.391",
+    "pytest>=8.3.4",
+    "ruff>=0.8.5",
     "trio>=0.26.2",
     "pytest-flakefinder>=1.1.0",
     "pytest-xdist>=3.6.1",
@@ -83,4 +83,4 @@ target-version = "py310"
 members = ["examples/servers/*"]
 
 [tool.uv.sources]
-mcp = { workspace = true }
+mcp = { workspace = true }

Diff for: src/mcp/cli/claude.py

@@ -87,7 +87,7 @@ def update_claude_config(
         args = ["run"]
 
         # Collect all packages in a set to deduplicate
-        packages = {"fastmcp"}
+        packages = {"mcp"}
         if with_packages:
             packages.update(pkg for pkg in with_packages if pkg)
 
@@ -107,7 +107,7 @@ def update_claude_config(
             file_spec = str(Path(file_spec).resolve())
 
         # Add fastmcp run command
-        args.extend(["fastmcp", "run", file_spec])
+        args.extend(["mcp", "run", file_spec])
 
         server_config = {
             "command": "uv",

Diff for: src/mcp/cli/cli.py

@@ -373,7 +373,7 @@ def install(
         list[str],
         typer.Option(
             "--env-var",
-            "-e",
+            "-v",
             help="Environment variables in KEY=VALUE format",
         ),
     ] = [],

Diff for: src/mcp/client/stdio.py

@@ -1,6 +1,7 @@
 import os
 import sys
 from contextlib import asynccontextmanager
+from typing import Literal
 
 import anyio
 import anyio.lowlevel
@@ -65,6 +66,21 @@ class StdioServerParameters(BaseModel):
     If not specified, the result of get_default_environment() will be used.
     """
 
+    encoding: str = "utf-8"
+    """
+    The text encoding used when sending/receiving messages to the server
+
+    defaults to utf-8
+    """
+
+    encoding_error_handler: Literal["strict", "ignore", "replace"] = "strict"
+    """
+    The text encoding error handler.
+
+    See https://docs.python.org/3/library/codecs.html#codec-base-classes for
+    explanations of possible values
+    """
+
 
 @asynccontextmanager
 async def stdio_client(server: StdioServerParameters):
@@ -93,7 +109,11 @@ async def stdout_reader():
         try:
             async with read_stream_writer:
                 buffer = ""
-                async for chunk in TextReceiveStream(process.stdout):
+                async for chunk in TextReceiveStream(
+                    process.stdout,
+                    encoding=server.encoding,
+                    errors=server.encoding_error_handler,
+                ):
                     lines = (buffer + chunk).split("\n")
                     buffer = lines.pop()
 
@@ -115,7 +135,12 @@ async def stdin_writer():
             async with write_stream_reader:
                 async for message in write_stream_reader:
                     json = message.model_dump_json(by_alias=True, exclude_none=True)
-                    await process.stdin.send((json + "\n").encode())
+                    await process.stdin.send(
+                        (json + "\n").encode(
+                            encoding=server.encoding,
+                            errors=server.encoding_error_handler,
+                        )
+                    )
         except anyio.ClosedResourceError:
             await anyio.lowlevel.checkpoint()
 

Diff for: src/mcp/server/fastmcp/server.py

@@ -423,9 +423,9 @@ async def run_stdio_async(self) -> None:
     async def run_sse_async(self) -> None:
         """Run the server using SSE transport."""
         from starlette.applications import Starlette
-        from starlette.routing import Route
+        from starlette.routing import Mount, Route
 
-        sse = SseServerTransport("/messages")
+        sse = SseServerTransport("/messages/")
 
         async def handle_sse(request):
             async with sse.connect_sse(
@@ -437,14 +437,11 @@ async def handle_sse(request):
                     self._mcp_server.create_initialization_options(),
                 )
 
-        async def handle_messages(request):
-            await sse.handle_post_message(request.scope, request.receive, request._send)
-
         starlette_app = Starlette(
             debug=self.settings.debug,
             routes=[
                 Route("/sse", endpoint=handle_sse),
-                Route("/messages", endpoint=handle_messages, methods=["POST"]),
+                Mount("/messages/", app=sse.handle_post_message),
             ],
         )
 

Diff for: src/mcp/server/lowlevel/server.py

@@ -101,8 +101,9 @@ def __init__(
 
 
 class Server:
-    def __init__(self, name: str):
+    def __init__(self, name: str, version: str | None = None):
         self.name = name
+        self.version = version
         self.request_handlers: dict[
             type, Callable[..., Awaitable[types.ServerResult]]
         ] = {
@@ -133,7 +134,7 @@ def pkg_version(package: str) -> str:
 
         return InitializationOptions(
             server_name=self.name,
-            server_version=pkg_version("mcp"),
+            server_version=self.version if self.version else pkg_version("mcp"),
             capabilities=self.get_capabilities(
                 notification_options or NotificationOptions(),
                 experimental_capabilities or {},

Diff for: src/mcp/server/sse.py

@@ -6,12 +6,12 @@
 Example usage:
 ```
     # Create an SSE transport at an endpoint
-    sse = SseServerTransport("/messages")
+    sse = SseServerTransport("/messages/")
 
     # Create Starlette routes for SSE and message handling
     routes = [
         Route("/sse", endpoint=handle_sse),
-        Route("/messages", endpoint=handle_messages, methods=["POST"])
+        Mount("/messages/", app=sse.handle_post_message),
     ]
 
     # Define handler functions
@@ -23,9 +23,6 @@ async def handle_sse(request):
                 streams[0], streams[1], app.create_initialization_options()
             )
 
-    async def handle_messages(request):
-        await sse.handle_post_message(request.scope, request.receive, request._send)
-
     # Create and run Starlette app
     starlette_app = Starlette(routes=routes)
     uvicorn.run(starlette_app, host="0.0.0.0", port=port)