Skip to content

Commit 982f6b0

Browse files
committed
Merge branch 'outputSchema' of https://github.com/davemssavage/python-sdk into outputSchema
2 parents 6d2882c + ecc7146 commit 982f6b0

File tree

42 files changed

+2660
-86
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+2660
-86
lines changed

.github/workflows/shared.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,11 @@ jobs:
3737
run: uv run --no-sync pyright
3838

3939
test:
40-
runs-on: ubuntu-latest
40+
runs-on: ${{ matrix.os }}
4141
strategy:
4242
matrix:
4343
python-version: ["3.10", "3.11", "3.12", "3.13"]
44+
os: [ubuntu-latest, windows-latest]
4445

4546
steps:
4647
- uses: actions/checkout@v4
@@ -55,3 +56,4 @@ jobs:
5556

5657
- name: Run pytest
5758
run: uv run --no-sync pytest
59+
continue-on-error: true

README.md

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -318,7 +318,7 @@ providing an implementation of the `OAuthServerProvider` protocol.
318318

319319
```
320320
mcp = FastMCP("My App",
321-
auth_provider=MyOAuthServerProvider(),
321+
auth_server_provider=MyOAuthServerProvider(),
322322
auth=AuthSettings(
323323
issuer_url="https://myapp.com",
324324
revocation_options=RevocationOptions(
@@ -387,6 +387,8 @@ python server.py
387387
mcp run server.py
388388
```
389389

390+
Note that `mcp run` or `mcp dev` only supports server using FastMCP and not the low-level server variant.
391+
390392
### Streamable HTTP Transport
391393

392394
> **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
@@ -400,6 +402,9 @@ mcp = FastMCP("StatefulServer")
400402
# Stateless server (no session persistence)
401403
mcp = FastMCP("StatelessServer", stateless_http=True)
402404

405+
# Stateless server (no session persistence, no sse stream with supported client)
406+
mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
407+
403408
# Run server with streamable_http transport
404409
mcp.run(transport="streamable-http")
405410
```
@@ -426,21 +431,28 @@ mcp = FastMCP(name="MathServer", stateless_http=True)
426431

427432

428433
@mcp.tool(description="A simple add tool")
429-
def add_two(n: int) -> str:
434+
def add_two(n: int) -> int:
430435
return n + 2
431436
```
432437

433438
```python
434439
# main.py
440+
import contextlib
435441
from fastapi import FastAPI
436442
from mcp.echo import echo
437443
from mcp.math import math
438444

439445

440-
app = FastAPI()
446+
# Create a combined lifespan to manage both session managers
447+
@contextlib.asynccontextmanager
448+
async def lifespan(app: FastAPI):
449+
async with contextlib.AsyncExitStack() as stack:
450+
await stack.enter_async_context(echo.mcp.session_manager.run())
451+
await stack.enter_async_context(math.mcp.session_manager.run())
452+
yield
453+
441454

442-
# Use the session manager's lifespan
443-
app = FastAPI(lifespan=lambda app: echo.mcp.session_manager.run())
455+
app = FastAPI(lifespan=lifespan)
444456
app.mount("/echo", echo.mcp.streamable_http_app())
445457
app.mount("/math", math.mcp.streamable_http_app())
446458
```
@@ -462,6 +474,8 @@ The streamable HTTP transport supports:
462474

463475
> **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
464476
477+
By default, SSE servers are mounted at `/sse` and Streamable HTTP servers are mounted at `/mcp`. You can customize these paths using the methods described below.
478+
465479
You can mount the SSE server to an existing ASGI server using the `sse_app` method. This allows you to integrate the SSE server with other ASGI applications.
466480

467481
```python
@@ -617,7 +631,7 @@ server = Server("example-server", lifespan=server_lifespan)
617631
# Access lifespan context in handlers
618632
@server.call_tool()
619633
async def query_db(name: str, arguments: dict) -> list:
620-
ctx = server.request_context
634+
ctx = server.get_context()
621635
db = ctx.lifespan_context["db"]
622636
return await db.query(arguments["query"])
623637
```
@@ -692,6 +706,8 @@ if __name__ == "__main__":
692706
asyncio.run(run())
693707
```
694708

709+
Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
710+
695711
### Writing MCP Clients
696712

697713
The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):

examples/clients/simple-chatbot/README.MD

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ This example demonstrates how to integrate the Model Context Protocol (MCP) into
2525
```plaintext
2626
LLM_API_KEY=your_api_key_here
2727
```
28+
**Note:** The current implementation is configured to use the Groq API endpoint (`https://api.groq.com/openai/v1/chat/completions`) with the `llama-3.2-90b-vision-preview` model. If you plan to use a different LLM provider, you'll need to modify the `LLMClient` class in `main.py` to use the appropriate endpoint URL and model parameters.
2829

2930
3. **Configure servers:**
3031

examples/servers/simple-auth/README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,31 @@ uv run mcp-simple-auth
4444

4545
The server will start on `http://localhost:8000`.
4646

47+
### Transport Options
48+
49+
This server supports multiple transport protocols that can run on the same port:
50+
51+
#### SSE (Server-Sent Events) - Default
52+
```bash
53+
uv run mcp-simple-auth
54+
# or explicitly:
55+
uv run mcp-simple-auth --transport sse
56+
```
57+
58+
SSE transport provides endpoint:
59+
- `/sse`
60+
61+
#### Streamable HTTP
62+
```bash
63+
uv run mcp-simple-auth --transport streamable-http
64+
```
65+
66+
Streamable HTTP transport provides endpoint:
67+
- `/mcp`
68+
69+
70+
This ensures backward compatibility without needing multiple server instances. When using SSE transport (`--transport sse`), only the `/sse` endpoint is available.
71+
4772
## Available Tool
4873

4974
### get_user_profile
@@ -61,5 +86,6 @@ If the server fails to start, check:
6186
1. Environment variables `MCP_GITHUB_GITHUB_CLIENT_ID` and `MCP_GITHUB_GITHUB_CLIENT_SECRET` are set
6287
2. The GitHub OAuth app callback URL matches `http://localhost:8000/github/callback`
6388
3. No other service is using port 8000
89+
4. The transport specified is valid (`sse` or `streamable-http`)
6490

6591
You can use [Inspector](https://github.com/modelcontextprotocol/inspector) to test Auth

examples/servers/simple-auth/mcp_simple_auth/__main__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@
44

55
from mcp_simple_auth.server import main
66

7-
sys.exit(main())
7+
sys.exit(main()) # type: ignore[call-arg]

examples/servers/simple-auth/mcp_simple_auth/server.py

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
import logging
44
import secrets
55
import time
6-
from typing import Any
6+
from typing import Any, Literal
77

88
import click
99
from pydantic import AnyHttpUrl
@@ -347,7 +347,13 @@ async def get_user_profile() -> dict[str, Any]:
347347
@click.command()
348348
@click.option("--port", default=8000, help="Port to listen on")
349349
@click.option("--host", default="localhost", help="Host to bind to")
350-
def main(port: int, host: str) -> int:
350+
@click.option(
351+
"--transport",
352+
default="sse",
353+
type=click.Choice(["sse", "streamable-http"]),
354+
help="Transport protocol to use ('sse' or 'streamable-http')",
355+
)
356+
def main(port: int, host: str, transport: Literal["sse", "streamable-http"]) -> int:
351357
"""Run the simple GitHub MCP server."""
352358
logging.basicConfig(level=logging.INFO)
353359

@@ -364,5 +370,6 @@ def main(port: int, host: str) -> int:
364370
return 1
365371

366372
mcp_server = create_simple_mcp_server(settings)
367-
mcp_server.run(transport="sse")
373+
logger.info(f"Starting server with {transport} transport")
374+
mcp_server.run(transport=transport)
368375
return 0

examples/servers/simple-prompt/mcp_simple_prompt/__main__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
from .server import main
44

5-
sys.exit(main())
5+
sys.exit(main()) # type: ignore[call-arg]

examples/servers/simple-resource/mcp_simple_resource/__main__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
from .server import main
44

5-
sys.exit(main())
5+
sys.exit(main()) # type: ignore[call-arg]

examples/servers/simple-resource/mcp_simple_resource/server.py

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
import click
33
import mcp.types as types
44
from mcp.server.lowlevel import Server
5-
from pydantic import FileUrl
5+
from pydantic import AnyUrl
66

77
SAMPLE_RESOURCES = {
88
"greeting": "Hello! This is a sample text resource.",
@@ -26,7 +26,7 @@ def main(port: int, transport: str) -> int:
2626
async def list_resources() -> list[types.Resource]:
2727
return [
2828
types.Resource(
29-
uri=FileUrl(f"file:///{name}.txt"),
29+
uri=AnyUrl(f"file:///{name}.txt"),
3030
name=name,
3131
description=f"A sample text resource named {name}",
3232
mimeType="text/plain",
@@ -35,7 +35,9 @@ async def list_resources() -> list[types.Resource]:
3535
]
3636

3737
@app.read_resource()
38-
async def read_resource(uri: FileUrl) -> str | bytes:
38+
async def read_resource(uri: AnyUrl) -> str | bytes:
39+
if uri.path is None:
40+
raise ValueError(f"Invalid resource path: {uri}")
3941
name = uri.path.replace(".txt", "").lstrip("/")
4042

4143
if name not in SAMPLE_RESOURCES:
Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
from .server import main
22

33
if __name__ == "__main__":
4-
main()
4+
# Click will handle CLI arguments
5+
import sys
6+
7+
sys.exit(main()) # type: ignore[call-arg]
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
from .server import main
22

33
if __name__ == "__main__":
4-
main()
4+
main() # type: ignore[call-arg]

examples/servers/simple-tool/mcp_simple_tool/__main__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22

33
from .server import main
44

5-
sys.exit(main())
5+
sys.exit(main()) # type: ignore[call-arg]

pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"
8585
packages = ["src/mcp"]
8686

8787
[tool.pyright]
88-
include = ["src/mcp", "tests"]
88+
include = ["src/mcp", "tests", "examples/servers"]
8989
venvPath = "."
9090
venv = ".venv"
9191
strict = ["src/mcp/**/*.py"]

src/mcp/__init__.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
from .client.session import ClientSession
2+
from .client.session_group import ClientSessionGroup
23
from .client.stdio import StdioServerParameters, stdio_client
34
from .server.session import ServerSession
45
from .server.stdio import stdio_server
@@ -63,6 +64,7 @@
6364
"ClientRequest",
6465
"ClientResult",
6566
"ClientSession",
67+
"ClientSessionGroup",
6668
"CreateMessageRequest",
6769
"CreateMessageResult",
6870
"ErrorData",

src/mcp/cli/cli.py

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@
66
import subprocess
77
import sys
88
from pathlib import Path
9-
from typing import Annotated
9+
from typing import Annotated, Any
10+
11+
from mcp.server import FastMCP
12+
from mcp.server import Server as LowLevelServer
1013

1114
try:
1215
import typer
@@ -141,17 +144,48 @@ def _import_server(file: Path, server_object: str | None = None):
141144
module = importlib.util.module_from_spec(spec)
142145
spec.loader.exec_module(module)
143146

147+
def _check_server_object(server_object: Any, object_name: str):
148+
"""Helper function to check that the server object is supported
149+
150+
Args:
151+
server_object: The server object to check.
152+
153+
Returns:
154+
True if it's supported.
155+
"""
156+
if not isinstance(server_object, FastMCP):
157+
logger.error(
158+
f"The server object {object_name} is of type "
159+
f"{type(server_object)} (expecting {FastMCP})."
160+
)
161+
if isinstance(server_object, LowLevelServer):
162+
logger.warning(
163+
"Note that only FastMCP server is supported. Low level "
164+
"Server class is not yet supported."
165+
)
166+
return False
167+
return True
168+
144169
# If no object specified, try common server names
145170
if not server_object:
146171
# Look for the most common server object names
147172
for name in ["mcp", "server", "app"]:
148173
if hasattr(module, name):
174+
if not _check_server_object(getattr(module, name), f"{file}:{name}"):
175+
logger.error(
176+
f"Ignoring object '{file}:{name}' as it's not a valid "
177+
"server object"
178+
)
179+
continue
149180
return getattr(module, name)
150181

151182
logger.error(
152183
f"No server object found in {file}. Please either:\n"
153184
"1. Use a standard variable name (mcp, server, or app)\n"
154-
"2. Specify the object name with file:object syntax",
185+
"2. Specify the object name with file:object syntax"
186+
"3. If the server creates the FastMCP object within main() "
187+
" or another function, refactor the FastMCP object to be a "
188+
" global variable named mcp, server, or app.",
155189
extra={"file": str(file)},
156190
)
157191
sys.exit(1)
@@ -179,6 +213,9 @@ def _import_server(file: Path, server_object: str | None = None):
179213
)
180214
sys.exit(1)
181215

216+
if not _check_server_object(server, server_object):
217+
sys.exit(1)
218+
182219
return server
183220

184221

0 commit comments

Comments
 (0)