README - replace code snippets with examples - add lowlevel to snippets #1150
Conversation
README.md
Outdated
| """Low-level server example showing structured output support. | ||
|
|
||
| This example demonstrates how to use the low-level server API to return | ||
| structured data from tools, with automatic validation against output schemas. | ||
|
|
||
| Run from the repository root: | ||
| uv run examples/snippets/servers/lowlevel/structured_output.py | ||
| """ |
There was a problem hiding this comment.
Those module docstring seems to be adding a lot of unnecessary content to the README, given that you can run each of those individually.
README.md
Outdated
| # WARNING: eval() is dangerous! Use a safe math parser in production | ||
| result = eval(expression) |
There was a problem hiding this comment.
I know we have the comment warning people, but maybe we can have an example that doesn't use it?
There was a problem hiding this comment.
Agree, maybe something like:
from sympy import sympify
...
result = sympify(expression).evalf()(and the extra dep can be added as uv preamble w/ uv add --script ...py sympy)
There was a problem hiding this comment.
just changed an example to weathers, same as we have for high level server API
README.md
Outdated
| except Exception as e: | ||
| raise ValueError(f"Calculation error: {str(e)}") |
There was a problem hiding this comment.
Out of scope, but this shouldn't be necessary, since the exception is just bubbled up?
There was a problem hiding this comment.
And/or, maybe always raise X() from e for exception chaining
README.md
Outdated
| if name != "example-prompt": | ||
| raise ValueError(f"Unknown prompt: {name}") | ||
|
|
||
| arg1_value = arguments.get("arg1", "default") if arguments else "default" |
There was a problem hiding this comment.
meganit: arg1_value = (arguments or {}).get("arg1", "default") to say default only once?
README.md
Outdated
| # WARNING: eval() is dangerous! Use a safe math parser in production | ||
| result = eval(expression) |
There was a problem hiding this comment.
Agree, maybe something like:
from sympy import sympify
...
result = sympify(expression).evalf()(and the extra dep can be added as uv preamble w/ uv add --script ...py sympy)
| and cleanup. | ||
|
|
||
| Run from the repository root: | ||
| uv run examples/snippets/servers/lowlevel/lifespan.py |
There was a problem hiding this comment.
Maybe need uv add --script examples/snippets/servers/lowlevel/lifespan.py mcp first to bake the dep(s) into each of these examples? Otherwise I'm getting:
error: Workspace member `/Users/ochafik/code/modelcontextprotocol-python-sdk/examples/servers/simple-auth-remote` is missing a `pyproject.toml` (matches: `examples/servers/*`)
|
|
||
| # low-level server will validate structured output against the tool's | ||
| # output schema, and automatically serialize it into a TextContent block | ||
| # for backwards compatibility with pre-2025-06-18 clients. |
There was a problem hiding this comment.
meganit: I'd maybe switch "automatically" to "additionally" to make it clearer that serialization is in addition to returning structuredContent?
README.md
Outdated
| except Exception as e: | ||
| raise ValueError(f"Calculation error: {str(e)}") |
There was a problem hiding this comment.
And/or, maybe always raise X() from e for exception chaining
Part 3:
Part 1: #1055
Part 2: #1136
Part 3: #1137
Remaining:
Auth
Remote MCP (streamable Http)