wehub-resource-sync
4782e08282
Conformance Tests / server-conformance (push) Waiting to run
Conformance Tests / client-conformance (push) Waiting to run
GitHub Actions Security Analysis / zizmor (push) Waiting to run
CI / all-green (push) Has been cancelled
CI / checks (push) Has been cancelled
136 lines
6.5 KiB
Markdown
136 lines
6.5 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/modelcontextprotocol/python-sdk) · [上游 README](https://github.com/modelcontextprotocol/python-sdk/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# MCP Python SDK
|
||
|
||
<div align="center">
|
||
|
||
<strong>Model Context Protocol（MCP）的 Python 实现</strong>
|
||
|
||
[![PyPI][pypi-badge]][pypi-url]
|
||
[![MIT licensed][mit-badge]][mit-url]
|
||
[![Python Version][python-badge]][python-url]
|
||
[![Documentation][docs-badge]][docs-url]
|
||
[![Protocol][protocol-badge]][protocol-url]
|
||
[![Specification][spec-badge]][spec-url]
|
||
|
||
</div>
|
||
|
||
> [!CAUTION]
|
||
> **本 README 记录的是 MCP Python SDK v2 —— 一条正在积极开发的预发布（alpha/beta）分支。请勿在生产环境使用 v2。** 预发布版本会发布到 PyPI，包名为 `2.0.0aN` / `2.0.0bN`，且**每个预发布版本相对前一版都可能包含破坏性变更**。请固定精确版本，并在提升版本 pin 时预期需要更新代码。
|
||
>
|
||
> **v1.x 是唯一稳定的发布分支，仍建议用于生产环境。** 它位于 [`v1.x` 分支](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x)，并继续接收关键 bug 修复和安全补丁；文档见 [v1.x README](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/README.md)。`pip` 和 `uv` 不会选择预发布版本，除非你显式请求，因此现有安装不受影响。**若你的包依赖 `mcp`，请在稳定版发布前，为版本约束添加上界 `<2`（例如 `mcp>=1.27,<2`）。**
|
||
>
|
||
> v2 是对 SDK 的一次重大重构，既是为了支持 [2026-07-28 MCP 规范发布](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/)，也是为了修复长期存在的架构问题。变更概览见 [v2 新特性](https://py.sdk.modelcontextprotocol.io/v2/whats-new/)，各项破坏性变更见 [迁移指南](https://py.sdk.modelcontextprotocol.io/v2/migration/)。稳定版 v2 计划于 2026-07-27 与规范同步发布。欢迎试用预发布版本，并[告诉我们哪里会出问题](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml),，或在 [MCP Contributors Discord 的 #python-sdk-dev](https://discord.gg/6CSzBmMkjX). 频道讨论。
|
||
|
||
## 文档
|
||
|
||
**文档地址：<https://py.sdk.modelcontextprotocol.io/v2/>。**
|
||
|
||
其中包含 [入门指南](https://py.sdk.modelcontextprotocol.io/v2/get-started/),、[v2 新特性](https://py.sdk.modelcontextprotocol.io/v2/whats-new/),、[API 参考](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/),，以及 [迁移指南](https://py.sdk.modelcontextprotocol.io/v2/migration/).。
|
||
|
||
## 什么是 MCP？
|
||
|
||
[Model Context Protocol](https://modelcontextprotocol.io)（MCP）让你能够以安全、标准化的方式构建向 LLM 应用暴露数据与功能的服务器。可以把它理解为面向 LLM 交互设计的 Web API。借助本 SDK，你可以：
|
||
|
||
- **构建 MCP 服务器**，向任意 MCP 主机暴露工具、资源和提示词
|
||
- **构建 MCP 客户端**，连接任意 MCP 服务器
|
||
- 支持所有标准传输方式：stdio、Streamable HTTP 和 SSE
|
||
|
||
## 环境要求
|
||
|
||
Python 3.10+。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
uv add "mcp[cli]==2.0.0b1" # or: pip install "mcp[cli]==2.0.0b1"
|
||
```
|
||
|
||
在 v2 处于预发布阶段时，版本 pin 很重要：未固定版本的安装会解析到最新的稳定版 v1.x，而本 README 并不描述该版本。可在 [PyPI](https://pypi.org/project/mcp/#history) 查看最新预发布版本，一次性命令可使用 `uv run --with "mcp==2.0.0b1"`。
|
||
|
||
## 15 行代码搭建一个服务器
|
||
|
||
创建一个 `server.py`：
|
||
|
||
<!-- snippet-source docs_src/index/tutorial001.py -->
|
||
```python
|
||
from mcp.server import MCPServer
|
||
|
||
mcp = MCPServer("Demo")
|
||
|
||
|
||
@mcp.tool()
|
||
def add(a: int, b: int) -> int:
|
||
"""Add two numbers."""
|
||
return a + b
|
||
|
||
|
||
@mcp.resource("greeting://{name}")
|
||
def greeting(name: str) -> str:
|
||
"""Greet someone by name."""
|
||
return f"Hello, {name}!"
|
||
```
|
||
|
||
_完整示例：[docs_src/index/tutorial001.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs_src/index/tutorial001.py)_
|
||
<!-- /snippet-source -->
|
||
|
||
这就是一个完整的 MCP 服务器：一个工具、一个模板化资源。在 [MCP Inspector](https://github.com/modelcontextprotocol/inspector): 中打开它。
|
||
|
||
```bash
|
||
uv run mcp dev server.py
|
||
```
|
||
|
||
使用 `a=1` 和 `b=2` 调用 `add`，即可得到 `3`。
|
||
|
||
注意你**没有**编写的内容：没有 JSON Schema（`a: int, b: int` _就是_ schema）、没有请求解析、没有校验代码、没有协议处理。只有两个带类型注解的 Python 函数和一个 docstring。
|
||
|
||
从这里继续阅读 [入门指南](https://py.sdk.modelcontextprotocol.io/v2/get-started/)。
|
||
|
||
## 10 行代码搭建一个客户端
|
||
|
||
同一个包也是完整的 MCP **客户端**。`Client` 可连接到 URL、stdio 子进程、自定义传输层，或（用于测试）直接连接内存中的服务器对象，完全无需传输层：
|
||
|
||
```python
|
||
import asyncio
|
||
|
||
from mcp import Client
|
||
|
||
from server import mcp
|
||
|
||
|
||
async def main() -> None:
|
||
async with Client(mcp) as client:
|
||
result = await client.call_tool("add", {"a": 1, "b": 2})
|
||
print(result.structured_content) # {'result': 3}
|
||
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
将 `mcp` 替换为 `"http://localhost:8000/mcp"`，同样的代码即可与远程服务器通信。
|
||
|
||
## 贡献
|
||
|
||
我们热忱欢迎各经验水平的贡献者参与，并期待你的加入。入门请阅读 [贡献指南](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)。
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT License 授权。详见 [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE) 文件。
|
||
|
||
[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg
|
||
[pypi-url]: https://pypi.org/project/mcp/
|
||
[mit-badge]: https://img.shields.io/pypi/l/mcp.svg
|
||
[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
|
||
[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
|
||
[python-url]: https://www.python.org/downloads/
|
||
[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
|
||
[docs-url]: https://py.sdk.modelcontextprotocol.io/v2/
|
||
[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
|
||
[protocol-url]: https://modelcontextprotocol.io
|
||
[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
|
||
[spec-url]: https://modelcontextprotocol.io/specification/latest
|