Spaces:
Running
Running
Jeremiah Lowin commited on
Commit ·
7e2826d
1
Parent(s): bf2f475
Update docs
Browse files- docs/servers/resources.mdx +25 -14
docs/servers/resources.mdx
CHANGED
|
@@ -225,17 +225,27 @@ However, function parameters with default values don't need to be included in th
|
|
| 225 |
- Extract parameter values from the URI for parameters included in the template
|
| 226 |
- Use default values for any function parameters not in the URI template
|
| 227 |
|
| 228 |
-
This allows for flexible API designs
|
| 229 |
-
|
| 230 |
-
#### Multiple URI Templates for the Same Function
|
| 231 |
-
|
| 232 |
-
A powerful pattern is registering a single function with multiple URI templates, allowing different ways to access the same data:
|
| 233 |
|
| 234 |
```python
|
| 235 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 236 |
|
| 237 |
-
|
|
|
|
|
|
|
| 238 |
|
|
|
|
| 239 |
# Define a user lookup function that can be accessed by different identifiers
|
| 240 |
@mcp.resource("users://email/{email}")
|
| 241 |
@mcp.resource("users://name/{name}")
|
|
@@ -250,13 +260,14 @@ def lookup_user(name: str | None = None, email: str | None = None) -> dict:
|
|
| 250 |
```
|
| 251 |
|
| 252 |
Now an LLM or client can retrieve user information in two different ways:
|
| 253 |
-
- `users://email/alice@example.com` → Looks up user by email
|
| 254 |
-
- `users://name/Bob` → Looks up user by name
|
| 255 |
-
|
| 256 |
-
In this pattern:
|
| 257 |
-
- The `name` parameter is only provided
|
| 258 |
-
- The `email` parameter is only provided
|
| 259 |
-
- Each parameter
|
|
|
|
| 260 |
|
| 261 |
**How Templates Work:**
|
| 262 |
|
|
|
|
| 225 |
- Extract parameter values from the URI for parameters included in the template
|
| 226 |
- Use default values for any function parameters not in the URI template
|
| 227 |
|
| 228 |
+
This allows for flexible API designs. For example, a simple search template with optional parameters:
|
|
|
|
|
|
|
|
|
|
|
|
|
| 229 |
|
| 230 |
```python
|
| 231 |
+
@mcp.resource("search://{query}")
|
| 232 |
+
def search_resources(query: str, max_results: int = 10, include_archived: bool = False) -> dict:
|
| 233 |
+
"""Search for resources matching the query string."""
|
| 234 |
+
# Only 'query' is required in the URI, the other parameters use their defaults
|
| 235 |
+
results = perform_search(query, limit=max_results, archived=include_archived)
|
| 236 |
+
return {
|
| 237 |
+
"query": query,
|
| 238 |
+
"max_results": max_results,
|
| 239 |
+
"include_archived": include_archived,
|
| 240 |
+
"results": results
|
| 241 |
+
}
|
| 242 |
+
```
|
| 243 |
|
| 244 |
+
With this template, clients can request `search://python` and the function will be called with `query="python", max_results=10, include_archived=False`. MCP Developers can still call the underlying `search_resources` function directly with more specific parameters.
|
| 245 |
+
|
| 246 |
+
An even more powerful pattern is registering a single function with multiple URI templates, allowing different ways to access the same data:
|
| 247 |
|
| 248 |
+
```python
|
| 249 |
# Define a user lookup function that can be accessed by different identifiers
|
| 250 |
@mcp.resource("users://email/{email}")
|
| 251 |
@mcp.resource("users://name/{name}")
|
|
|
|
| 260 |
```
|
| 261 |
|
| 262 |
Now an LLM or client can retrieve user information in two different ways:
|
| 263 |
+
- `users://email/alice@example.com` → Looks up user by email (with name=None)
|
| 264 |
+
- `users://name/Bob` → Looks up user by name (with email=None)
|
| 265 |
+
|
| 266 |
+
In this stacked decorator pattern:
|
| 267 |
+
- The `name` parameter is only provided when using the `users://name/{name}` template
|
| 268 |
+
- The `email` parameter is only provided when using the `users://email/{email}` template
|
| 269 |
+
- Each parameter defaults to `None` when not included in the URI
|
| 270 |
+
- The function logic handles whichever parameter is provided
|
| 271 |
|
| 272 |
**How Templates Work:**
|
| 273 |
|