模型上下文协议（Model Context Protocol，MCP）Python SDK 文档

简介

模型上下文协议 (MCP) 是一个开放的协议，用于在语言模型与应用程序之间建立标准化接口。通过 MCP，开发者可以创建高度交互式的应用，其中模型可以直接调用外部工具和资源。

MCP Python SDK 提供了一套简单易用的 API，帮助开发者快速集成 MCP 功能到他们的项目中。

安装

使用 pip 安装最新版本的 MCP SDK：

pip install mcp-sdk

示例代码

基本使用

以下是 MCP 的基本使用示例：

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 创建连接到 MCP 服务器的参数
server_params = StdioServerParameters(
    command="python", # 执行文件路径
    args=["example_server.py"], # 可选的命令行参数
    env=None # 可选的环境变量
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化连接
            await session.initialize()

            # 列出可用提示模板
            prompts = await session.list_prompts()

            # 获取一个提示模板
            prompt = await session.get_prompt("example-prompt", arguments={"arg1": "value"})

if __name__ == "__main__":
    import asyncio
    asyncio.run(run())

高级用法

低级别服务器实现

如果你需要更底层的控制，可以直接使用低级别服务器实现：

from mcp.server.lowlevel import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
import mcp.types as types

# 创建一个服务器实例
server = Server("example-server")

@server.list_prompts()
async def handle_list_prompts() -> list[types.Prompt]:
    return [
        types.Prompt(
            name="example-prompt",
            description="一个示例提示模板",
            arguments=[
                types.PromptArgument(
                    name="arg1",
                    description="示例参数",
                    required=True
                )
            ]
        )
    ]

@server.get_prompt()
async def handle_get_prompt(
    name: str,
    arguments: dict[str, Any] | None
) -> types.GetPromptResult:
    if name != "example-prompt":
        raise ValueError(f"未知提示模板：{name}")

    return types.GetPromptResult(
        description="示例提示",
        messages=[
            types.PromptMessage(
                role="user",
                content=types.TextContent(
                    type="text",
                    text="示例提示文本"
                )
            )
        ]
    )

async def run():
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="example",
                server_version="0.1.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                ),
            ),
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(run())

提示模板

# 创建一个提示模板
from mcp.types import Prompt, PromptArgument

prompt = Prompt(
    name="example-prompt",
    description="这是一个示例提示模板。",
    arguments=[
        PromptArgument(
            name="input_text",
            description="输入文本。",
            required=True
        )
    ]
)

# 获取提示模板
async def get_prompt():
    prompt = await session.get_prompt("example-prompt", arguments={"input_text": "你好，世界！"})
    print(prompt)

资源

# 创建一个资源
from mcp.types import Resource, FileResource

resource = Resource(
    name="example-resource",
    description="这是一个示例资源。",
    type=FileResource,
    path="path/to/resource"
)

# 获取资源
async def get_resource():
    resource = await session.get_resource("example-resource")
    print(resource)

工具

# 创建一个工具
from mcp.types import Tool, FunctionTool

tool = Tool(
    name="example-tool",
    description="这是一个示例工具。",
    type=FunctionTool,
    function=lambda x: f"Hello, {x}"
)

# 获取工具
async def get_tool():
    tool = await session.get_tool("example-tool")
    print(tool)

MCP 基础原语

提示模板（Prompts）

提示模板是模型与用户交互的方式。MCP 定义了以下几种类型的提示模板：

• SystemPrompt：定义系统的角色和行为。
• UserPrompt：接收用户的输入并生成响应。
• ExamplePrompt：提供给模型的示例，帮助其理解如何处理特定任务。

资源（Resources）

资源是 MCP 中的重要组成部分。MCP 支持以下类型的资源：

• FileResource：加载和管理文件。
• URLResource：从网络 URL 加载内容。
• MemoryResource：在内存中临时存储数据。

工具（Tools）

工具允许模型调用外部服务或脚本执行特定任务。MCP 定义了多种工具类型：

• FunctionTool：将函数作为工具注册，模型可以直接调用这些函数。
• WebServiceTool：与 HTTP 服务交互。
• ScriptTool：执行预写的脚本。

服务器能力

MCP 定义了一系列服务器能力，使模型能够根据需要动态加载和管理资源：

• BasicCapability：最基础的能力，提供对提示模板、工具和资源的基本操作。
• ExtendedCapability：扩展功能，包括高级查询、过滤和排序等。
• CustomCapability：允许开发者自定义服务器功能。

文献资料

参考文档

• MCP 协议规范
• MCP 官方文档

示例代码仓库

• 官方示例
• 社区贡献的示例

贡献指南

如果你希望为 MCP 项目做出贡献，请参考我们的贡献指南，了解如何参与代码开发、报告问题或提出新功能。

许可证

MCP Python SDK 采用 MIT License 协议。更多详细信息请查看许可证文件。