Fastmcp Extensions

FastMCP扩展

FastMCP 2.0的非官方扩展库，包含构建MCP服务器的模式、实践和实用程序。

特性

• MCP服务器工厂： mcp_server() 帮助创建具有内置服务器信息资源、MCP资产发现（可选）和凭据解析的FastMCP实例。
• MCP注释常量：标准注释提示(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)遵循FastMCP 2.2.7+规范
• 延迟注册装饰者： @mcp_tool, @mcp_prompt, @mcp_resource 用于通过自动域检测按域组织工具的装饰器。
• 注册实用程序：在FastMCP应用程序中注册工具、提示和资源的功能，按域过滤。
• 工具测试实用程序：用于直接使用JSON参数（stdio和HTTP传输）测试MCP工具的帮助程序。
• 工具列表测量：用于测量工具列表大小以跟踪上下文截断问题的实用程序。
• 提示助手：通用 get_prompt_text 为无法直接访问提示资产的代理提供帮助。

安装

pip install fastmcp-extensions

或者使用紫外线：

uv add fastmcp-extensions

快速开始

使用MCP服务器工厂

这 mcp_server 函数创建了一个具有内置服务器信息资源和可选凭据解析的FastMCP实例：

from fastmcp_extensions import mcp_server, MCPServerConfigArg

app = mcp_server(
    name="my-mcp-server",
    package_name="my-package",
    advertised_properties={
        "docs_url": "https://github.com/org/repo",
        "release_history_url": "https://github.com/org/repo/releases",
    },
    server_config_args=[
        MCPServerConfigArg(
            name="api_key",
            http_header_key="X-API-Key",
            env_var="MY_API_KEY",
            required=True,
            sensitive=True,
        ),
    ],
)

# Server info resource is automatically registered at {name}://server/info
# Get credentials from HTTP headers or environment variables
from fastmcp_extensions import get_mcp_config
api_key = get_mcp_config(app, "api_key")

使用注释常量

from fastmcp_extensions import (
    READ_ONLY_HINT,
    DESTRUCTIVE_HINT,
    IDEMPOTENT_HINT,
    OPEN_WORLD_HINT,
)

# Use in tool annotations
annotations = {
    READ_ONLY_HINT: True,
    IDEMPOTENT_HINT: True,
}

使用延迟注册

from fastmcp import FastMCP
from fastmcp_extensions import mcp_tool, mcp_resource, register_mcp_tools, register_mcp_resources

# Define tools with the decorator (domain auto-detected from filename)
@mcp_tool(read_only=True, idempotent=True)
def list_items() -> list[str]:
    """List all available items."""
    return ["item1", "item2"]

@mcp_resource("myserver://version", "Server version", "application/json")
def get_version() -> dict:
    """Get server version info."""
    return {"version": "1.0.0"}

# Register with FastMCP app
app = FastMCP("my-server")
register_mcp_tools(app)
register_mcp_resources(app)

测量工具清单尺寸

import asyncio
from fastmcp_extensions.measurement import measure_tool_list_detailed

async def check_tool_size():
    measurement = await measure_tool_list_detailed(app, server_name="my-server")
    print(measurement)
    # Output:
    # MCP Server: my-server
    # Tool count: 10
    # Total characters: 5,432
    # Average chars per tool: 543

asyncio.run(check_tool_size())

测试工具

from fastmcp_extensions.testing import call_mcp_tool, run_tool_test
import asyncio

# Call a tool programmatically
result = asyncio.run(call_mcp_tool(app, "list_items", {}))

# Or use the CLI helper
run_tool_test(app, "list_items", '{}')

获取提示文本

from fastmcp_extensions.prompts import get_prompt_text
import asyncio

# Get prompt text for agents that can't access prompts directly
text = asyncio.run(get_prompt_text(app, "my_prompt", {"arg": "value"}))

MCP服务器的Poe任务

此库为常见的MCP开发任务提供模板脚本。将这些复制到您的项目中并进行自定义：

• bin/test_mcp_tool.py -通过stdio使用JSON参数的测试工具
• bin/test_mcp_tool_http.py -基于HTTP传输的测试工具
• bin/measure_mcp_tool_list.py -测量工具列表大小

添加到您的 poe_tasks.toml:

[tool.poe.tasks.mcp-tool-test]
help = "Test MCP tools directly with JSON arguments"
cmd = "python bin/test_mcp_tool.py"

[tool.poe.tasks.mcp-tool-test-http]
help = "Test MCP tools over HTTP transport"
cmd = "python bin/test_mcp_tool_http.py"

[tool.poe.tasks.mcp-measure-tools]
help = "Measure the size of the MCP tool list output"
cmd = "python bin/measure_mcp_tool_list.py"

API 参考

服务器工厂

• mcp_server -创建一个具有内置服务器信息资源和装饰工具和资产自动注册的FastMCP实例。
• MCPServerConfigArg -凭据解析和其他服务器设置的配置。
• get_mcp_config -从HTTP标头或环境变量中获取凭据。

注释

装饰器

• @mcp_tool(domain, read_only, destructive, idempotent, open_world, extra_help_text) -标记延迟注册工具
• @mcp_prompt(name, description, domain) -标记延迟注册提示
• @mcp_resource(uri, description, mime_type, domain) -标记资源以延迟注册

注册功能

• register_mcp_tools(app, domain, exclude_args) -在FastMCP应用程序中注册工具
• register_mcp_prompts(app, domain) -使用FastMCP应用程序注册提示
• register_mcp_resources(app, domain) -使用FastMCP应用程序注册资源

测试工具

• call_mcp_tool(app, tool_name, args) -异步调用工具
• list_mcp_tools(app) -列出所有可用工具
• run_tool_test(app, tool_name, json_args) -使用JSON参数运行工具测试
• run_http_tool_test(http_server_command, port, tool_name, args, env) -HTTP测试

测量工具

• measure_tool_list(app) -获取（tool_count，total_chars）元组
• measure_tool_list_detailed(app, server_name) -获取详细测量结果
• get_tool_details(app) -获取每个工具的尺寸细分

提示实用程序

• get_prompt_text(app, prompt_name, arguments) -获取提示文本内容
• list_prompts(app) -列出所有可用提示

发展

# Install dependencies
uv sync --extra dev

# Run tests
uv run poe test

# Format and lint
uv run poe fix

# Run all checks
uv run poe check

许可证

MIT许可证-请参阅 许可证 了解详情。