内容
# mcpatom
极简Python [MCP](https://modelcontextprotocol.io) 服务器SDK。
源自希腊语 *atomos*: 不可分割。整个库是一个单独的文件，
`mcpatom.py`，有两种使用方式：
- **复制文件** 到你的项目中。无需依赖，无需锁定文件记录。
- **安装包**: `pip install mcpatom` - 文件本身就是安装的模块。
## 范围
- 工具、资源和提示，通过标准输入输出或可流式HTTP。
- 协议版本 `2025-06-18` 和 `2025-11-25`。
- 仅限标准库的Python >= 3.10，无依赖。
其他功能（采样、诱导、订阅、身份验证等）被故意省略。
## 用法
```python
from mcpatom import Server
srv = Server("my-server")
@srv.tool
def greet(name: str, excited: bool = False) -> str:
"""返回给定名字的问候语."""
return f"你好，{name}{'!' if excited else '.'}"
@srv.resource("data://motd")
def motd() -> str:
"""今日消息."""
return "不可分割。"
@srv.prompt
def haiku(topic: str) -> str:
"""请求一首俳句."""
return f"写一首关于 {topic} 的俳句。"
srv.serve_stdio()
```
若要使用可流式HTTP代替标准输入输出，请以以下方式结尾：
```python
srv.serve_http(8388) # http://127.0.0.1:8388/mcp
```
`serve_http` 绑定到环回地址并拒绝DNS重新绑定请求；
`host="0.0.0.0"` 放宽绑定并关闭这些检查。
更多可运行的服务器请参见 [examples/](examples/)。
## 模式和返回类型
每个函数的名称、文档字符串和注解成为工具的名称、描述和模式；
`@srv.tool(name=, description=, input_schema=, output_schema=)` 重写生成，
`extra=` 合并原始字段到列表中。`Server()` 还接受 `version=` 和 `instructions=`。
参数可以注解为以下任意一种：
- `str`
- `int`
- `float`
- `bool`
- `list[X]` （或裸 `list`）
- `Literal[...]`
- `TypedDict`
- `X | None` 以上任意一种
`Annotated[X, "text"]` 为模型添加描述。
工具可以返回：
- `str` - 一个文本块
- `dict` - JSON文本加上 `structuredContent`；`TypedDict` 返回注解发布匹配的 `outputSchema`
- `Image(data, mime_type)` / `Audio(data, mime_type)` - 一个二进制块（输入为原始字节，传输时为base64）
- 元组 - 每个项目一个块：`str` 文本，`Image`/`Audio` 媒体，一个字典，其 `"type"` 命名一个规范块类型（例如 `resource_link`)
- `None` - 空内容；其他任何JSON值 - 文本
抛出异常是错误API：任何异常成为 `isError` 内容，模型可以读取并纠正。
资源返回 `str` （文本）或 `bytes` （base64大块）。
提示仅接受 `str` 参数并返回 `str` 用户消息，或消息字典列表原样传递。
## 连接
```sh
claude mcp add my-server -- /abs/path/.venv/bin/python /abs/path/server.py
```
或在任何 `mcpServers` 配置中：
```json
{"mcpServers": {"my-server": {"command": "/abs/path/.venv/bin/python", "args": ["/abs/path/server.py"]}}}
```
无需客户端的烟雾测试：
```sh
echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | python server.py
# {"jsonrpc":"2.0","id":1,"result":{}}
```
