ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-22 21:44:18 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #792 from jlowin/tags

Browse source 
Fix issue with global OpenAPI tags
This commit is contained in:
Jeremiah Lowin 2025-06-10 21:16:29 -04:00 • committed by GitHub
commit c29b386501
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 97 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

80
docs/servers/openapi.mdx
View file

@ -51,6 +51,7 @@ Each `RouteMap` specifies a combination of methods, patterns, and tags, as well
- **Pattern**: Regex pattern to match the route path (e.g. `r"^/users/.*"` or `r".*"` for all)
- **Tags**: A set of OpenAPI tags that must all be present. An empty set (`{}`) means no tag filtering, so the route matches regardless of its tags.
- **MCP type**: What MCP component type to create (`TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, or `EXCLUDE`)
- **MCP tags** A set of custom tags to add to components created from matching routes
Here is FastMCP's default rule:
@ -206,9 +207,76 @@ mcp = FastMCP.from_openapi(
## Customizing MCP Components
### Tags
<VersionBadge version="2.8.0" />
FastMCP provides several ways to add tags to your MCP components, allowing you to categorize and organize them for better discoverability and filtering. Tags are combined from multiple sources to create the final set of tags on each component.
#### RouteMap Tags
You can add custom tags to components created from specific routes using the `mcp_tags` parameter in `RouteMap`. These tags will be applied to all components created from routes that match that particular route map.
```python {12, 20, 28}
from fastmcp import FastMCP
from fastmcp.server.openapi import RouteMap, MCPType
mcp = FastMCP.from_openapi(
...,
route_maps=[
# Add custom tags to all POST endpoints
RouteMap(
methods=["POST"],
pattern=r".*",
mcp_type=MCPType.TOOL,
mcp_tags={"write-operation", "api-mutation"}
),
# Add different tags to detail view endpoints
RouteMap(
methods=["GET"],
pattern=r".*\{.*\}.*",
mcp_type=MCPType.RESOURCE_TEMPLATE,
mcp_tags={"detail-view", "parameterized"}
),
# Add tags to list endpoints
RouteMap(
methods=["GET"],
pattern=r".*",
mcp_type=MCPType.RESOURCE,
mcp_tags={"list-data", "collection"}
),
],
)
```
#### Global Tags
You can add tags to **all** components by providing a `tags` parameter when creating your FastMCP server with `from_openapi` or `from_fastapi`. These global tags will be applied to every component created from your OpenAPI specification.
<CodeGroup>
```python {6} from_openapi()
from fastmcp import FastMCP
mcp = FastMCP.from_openapi(
openapi_spec=spec,
client=client,
tags={"api-v2", "production", "external"}
)
```
```python {5} from_fastapi()
from fastmcp import FastMCP
mcp = FastMCP.from_fastapi(
app=app,
tags={"internal-api", "microservice"}
)
```
</CodeGroup>
### Component Names
### Names
<VersionBadge version="2.5.0" />
@ -421,10 +489,16 @@ mcp = FastMCP.from_fastapi(
app=app,
name="My Custom Server",
timeout=5.0,
tags={"api-v1", "fastapi"}, # Global tags for all components
mcp_names={"operationId": "friendly_name"}, # Custom component names
route_maps=[
# Admin endpoints become tools
RouteMap(methods="*", pattern=r"^/admin/.*", mcp_type=MCPType.TOOL),
# Admin endpoints become tools with custom tags
RouteMap(
methods="*",
pattern=r"^/admin/.*",
mcp_type=MCPType.TOOL,
mcp_tags={"admin", "privileged"}
),
# Internal endpoints are excluded
RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.EXCLUDE, tags={"internal"}),
],

7
src/fastmcp/server/server.py
View file

@ -121,7 +121,6 @@ class FastMCP(Generic[LifespanResultT]):
]
| None
) = None,
tags: set[str] | None = None,
tool_serializer: Callable[[Any], str] | None = None,
cache_expiration_seconds: float | None = None,
on_duplicate_tools: DuplicateBehavior | None = None,
@ -152,8 +151,6 @@ class FastMCP(Generic[LifespanResultT]):
resource_prefix_format or fastmcp.settings.resource_prefix_format
)
self.tags: set[str] = tags or set()
self._cache = TimedCache(
expiration=datetime.timedelta(seconds=cache_expiration_seconds or 0)
)
@ -1561,6 +1558,7 @@ class FastMCP(Generic[LifespanResultT]):
route_map_fn: OpenAPIRouteMapFn | None = None,
mcp_component_fn: OpenAPIComponentFn | None = None,
mcp_names: dict[str, str] | None = None,
tags: set[str] | None = None,
**settings: Any,
) -> FastMCPOpenAPI:
"""
@ -1575,6 +1573,7 @@ class FastMCP(Generic[LifespanResultT]):
route_map_fn=route_map_fn,
mcp_component_fn=mcp_component_fn,
mcp_names=mcp_names,
tags=tags,
**settings,
)
@ -1588,6 +1587,7 @@ class FastMCP(Generic[LifespanResultT]):
mcp_component_fn: OpenAPIComponentFn | None = None,
mcp_names: dict[str, str] | None = None,
httpx_client_kwargs: dict[str, Any] | None = None,
tags: set[str] | None = None,
**settings: Any,
) -> FastMCPOpenAPI:
"""
@ -1615,6 +1615,7 @@ class FastMCP(Generic[LifespanResultT]):
route_map_fn=route_map_fn,
mcp_component_fn=mcp_component_fn,
mcp_names=mcp_names,
tags=tags,
**settings,
)

2
tests/deprecated/test_settings.py
View file

@ -175,7 +175,6 @@ class TestDeprecatedServerInitKwargs:
server = FastMCP(
name="TestServer",
instructions="Test instructions",
tags={"test", "server"},
cache_expiration_seconds=60.0,
on_duplicate_tools="warn",
on_duplicate_resources="error",
@ -193,7 +192,6 @@ class TestDeprecatedServerInitKwargs:
# Verify server was created successfully
assert server.name == "TestServer"
assert server.instructions == "Test instructions"
assert server.tags == {"test", "server"}
def test_none_values_no_warnings(self):
"""Test that None values for deprecated kwargs don't raise warnings."""

40
tests/server/openapi/test_openapi.py
View file

@ -2709,25 +2709,22 @@ class TestGlobalTagsParameter:
)
# Check tool has both original and global tags
tools = server._tool_manager.list_tools()
create_item_tool = next((t for t in tools if "create_item" in t.name), None)
assert create_item_tool is not None
tools = await server.get_tools()
create_item_tool = tools["create_item_items_post"]
assert "items" in create_item_tool.tags # Original OpenAPI tag
assert "global" in create_item_tool.tags # Global tag
assert "api-v1" in create_item_tool.tags # Global tag
# Check resource has both original and global tags
resources = list(server._resource_manager.get_resources().values())
get_items_resource = next((r for r in resources if "get_items" in r.name), None)
assert get_items_resource is not None
resources = await server.get_resources()
get_items_resource = resources["resource://get_items_items_get"]
assert "items" in get_items_resource.tags # Original OpenAPI tag
assert "global" in get_items_resource.tags # Global tag
assert "api-v1" in get_items_resource.tags # Global tag
# Check resource template has both original and global tags
templates = list(server._resource_manager.get_templates().values())
get_item_template = next((t for t in templates if "get_item" in t.name), None)
assert get_item_template is not None
templates = await server.get_resource_templates()
get_item_template = templates["resource://get_item_items/{item_id}"]
assert "items" in get_item_template.tags # Original OpenAPI tag
assert "global" in get_item_template.tags # Global tag
assert "api-v1" in get_item_template.tags # Global tag
@ -2754,25 +2751,22 @@ class TestGlobalTagsParameter:
)
# Check tool has both original and global tags
tools = server._tool_manager.list_tools()
create_item_tool = next((t for t in tools if "create_item" in t.name), None)
assert create_item_tool is not None
tools = await server.get_tools()
create_item_tool = tools["create_item_items_post"]
assert "items" in create_item_tool.tags # Original OpenAPI tag
assert "openapi-global" in create_item_tool.tags # Global tag
assert "service" in create_item_tool.tags # Global tag
# Check resource has both original and global tags
resources = list(server._resource_manager.get_resources().values())
get_items_resource = next((r for r in resources if "get_items" in r.name), None)
assert get_items_resource is not None
resources = await server.get_resources()
get_items_resource = resources["resource://get_items_items_get"]
assert "items" in get_items_resource.tags # Original OpenAPI tag
assert "openapi-global" in get_items_resource.tags # Global tag
assert "service" in get_items_resource.tags # Global tag
# Check resource template has both original and global tags
templates = list(server._resource_manager.get_templates().values())
get_item_template = next((t for t in templates if "get_item" in t.name), None)
assert get_item_template is not None
templates = await server.get_resource_templates()
get_item_template = templates["resource://get_item_items/{item_id}"]
assert "items" in get_item_template.tags # Original OpenAPI tag
assert "openapi-global" in get_item_template.tags # Global tag
assert "service" in get_item_template.tags # Global tag
@ -2800,17 +2794,15 @@ class TestGlobalTagsParameter:
)
# Check that all three types of tags are present on the tool
tools = server._tool_manager.list_tools()
create_item_tool = next((t for t in tools if "create_item" in t.name), None)
assert create_item_tool is not None
tools = await server.get_tools()
create_item_tool = tools["create_item_items_post"]
assert "items" in create_item_tool.tags # Original OpenAPI tag
assert "global" in create_item_tool.tags # Global tag
assert "route-specific" in create_item_tool.tags # RouteMap mcp_tag
# Check that resource only has OpenAPI and global tags (no route-specific since different RouteMap)
resources = list(server._resource_manager.get_resources().values())
get_items_resource = next((r for r in resources if "get_items" in r.name), None)
assert get_items_resource is not None
resources = await server.get_resources()
get_items_resource = resources["resource://get_items_items_get"]
assert "items" in get_items_resource.tags # Original OpenAPI tag
assert "global" in get_items_resource.tags # Global tag
assert "route-specific" not in get_items_resource.tags # Not from this RouteMap