内容
# BridgeMCP
[](https://github.com/Arsie-codes/bridgemcp/actions/workflows/tests.yml)
[](https://pypi.org/project/bridgemcp-py/)
[](https://pypi.org/project/bridgemcp-py/)
[](LICENSE)
**一款适用于构建MCP服务器的生产-ready Python框架。**
BridgeMCP使得通过[模型上下文协议](https://modelcontextprotocol.io)向Claude Desktop、Cursor和VS Code等AI客户端公开应用程序的数据和操作变得简单。
编写您的业务逻辑。BridgeMCP处理协议。
---
## 为什么选择BridgeMCP
MCP Python SDK功能强大但级别较低。构建真正的服务器意味着在编写一行业务逻辑之前，需要连接传输层、手工制作JSON模式、管理工具调度并处理协议错误。
BridgeMCP在干净的基于装饰器的API后面封装了所有这些：
| 没有BridgeMCP | 使用BridgeMCP |
|---|---|
| 手动定义JSON模式 | 从类型注释中推断 |
| 编写协议处理程序 | `@app.tool`装饰器 |
| 管理错误代码 | 类型化的异常层次结构 |
| 选择和连接传输 | `app.run()`或`app.run_http()` |
---
## 安装
```bash
# 带有MCP传输支持
pip install 'bridgemcp-py[mcp]'
# 仅核心（无传输 - 在测试中仅需app.call()时有用）
pip install bridgemcp-py
```
需要Python 3.11+。
---
## 快速入门
**1. 编写您的服务器** (`server.py`):
```python
from bridgemcp import BridgeMCP
app = BridgeMCP(name="my-app", version="1.0.0", description="我的第一个MCP服务器。")
@app.tool
def greet(name: str) -> str:
"""向某人问好。"""
return f"你好，{name}!"
@app.tool
def add(x: int, y: int) -> int:
"""添加两个整数。"""
return x + y
if __name__ == "__main__":
app.run()
```
**2. 连接到Claude Desktop**
编辑您的Claude Desktop配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"my-app": {
"command": "python",
"args": ["/absolute/path/to/server.py"]
}
}
}
```
重启Claude Desktop。您的工具将出现在工具选择器中。
---
## 核心概念
### 创建应用程序
```python
from bridgemcp import BridgeMCP
from bridgemcp.config import BridgeConfig
app = BridgeMCP(
name="my-app", # 在MCP握手期间向AI客户端显示
version="1.0.0", # 默认值为已安装的软件包版本
description="...", # 可选 - 显示为服务器说明
config=BridgeConfig(),
)
```
### 注册工具
使用`@app.tool`作为裸装饰器或带有关键字参数：
```python
# 裸 - 自动使用函数名和文档字符串
@app.tool
def get_order(order_id: str) -> dict:
"""按ID获取订单。"""
return orders.get(order_id)
# 带有重写
@app.tool(name="list_orders", description="列出所有开放订单。")
def fetch_open_orders(limit: int = 20) -> list:
return orders.list(status="open", limit=limit)
```
类型注释成为AI客户端用于调用您的工具的JSON模式。默认值成为可选参数。文档字符串成为工具描述。
### 直接调用工具
装饰后的函数保持不变，因此您可以在测试中调用它而不必接触框架：
```python
# 直接调用 - 无框架参与
assert get_order("ORD-123") == {"id": "ORD-123", ...}
# 通过框架 - 注册查找 + 错误包装
result = app.call("get_order", order_id="ORD-123")
```
### 运行服务器
```python
# stdio - 子进程传输（Claude Desktop，Cursor，VS Code）
app.run()
# HTTP/SSE - 网络传输
app.run_http(host="0.0.0.0", port=8000)
```
---
## 异常层次结构
所有BridgeMCP异常都继承自`BridgeMCPError`：
```python
from bridgemcp.exceptions import (
BridgeMCPError, # 基础 - 捕获此异常以处理任何框架错误
# 工具
ToolNotFoundError, # 由app.call()在工具名称未知时引发
ToolRegistrationError, # 由@app.tool在名称已被占用时引发
ToolExecutionError, # 在工具函数本身引发时引发
# 资源
ResourceNotFoundError, # 由app.read_resource()在URI未知时引发
ResourceRegistrationError, # 由@app.resource在URI已被占用时引发
ResourceExecutionError, # 在资源处理程序引发时引发
# 提示
PromptNotFoundError, # 由app.render_prompt()在名称未知时引发
PromptRegistrationError, # 由@app.prompt在名称已被占用时引发
PromptExecutionError, # 在提示处理程序引发时引发
)
# 原始异常始终可通过执行错误时的__cause__访问。
```
---
## 架构
```
bridgemcp/
├── application.py # BridgeMCP - 单一公共入口点
├── config/ # BridgeConfig（Pydantic，冻结）
├── exceptions.py # 类型化的异常层次结构
├── execution.py # 处理程序执行管道（所有基元共享）
├── middleware.py # InvocationContext，MiddlewareFn，build_chain（）
├── plugin.py # 插件基类和鸭子类型约定
├── tools/ # 工具数据类 + ToolRegistry
├── resources/ # 资源数据类 + ResourceRegistry
├── prompts/ # Prompt，PromptMessage，PromptRegistry
└── adapters/ # 协议适配器（仅在此处导入MCP SDK）
└── mcp.py # build_mcp_server（）→ FastMCP
```
框架有意设计为分层：
1. **`BridgeMCP`**拥有整个公共API - 装饰器、调用方法、`run（）`。
2. **注册模块**独立于任何协议存储基元元数据。
3. **`execution.py`**处理调用、异常链接和输出规范。
4. **`middleware.py`**定义组合层 - 无框架导入。
5. **`adapters/mcp.py`**是唯一导入MCP SDK的地方。
由于MCP SDK是可选依赖项，`BridgeMCP`和所有调用方法在没有它的情况下都有效。您的单元测试在没有MCP导入的情况下运行，保持快速和业务逻辑与传输解耦。
---
## 示例
| 示例 | 描述 |
|---|---|
| [`examples/hello_world/`](examples/hello_world/server.py) | 极简服务器 - greet，add，server_info工具 |
---
## 开发
```bash
# 克隆并在可编辑模式下安装所有开发依赖项
git clone https://github.com/Arsie-codes/bridgemcp.git
cd bridgemcp
pip install -e '.[mcp,dev]'
# 运行测试套件
pytest
# 运行特定测试文件
pytest tests/test_tool_registry.py -v
# 检查和格式化
ruff check bridgemcp tests
black bridgemcp tests
```
测试套件不需要网络访问和MCP客户端 - 它完全在进程内框架上运行。
---
## 核心内容
| 功能 | API |
|---|---|
| 工具 | `@app.tool`，`app.call（）`，`await app.acall（）`，`app.list_tools（）` |
| 资源 | `@app.resource（uri = ...）`，`app.read_resource（）`，`await app.aread_resource（）`，`app.list_resources（）` |
| 提示 | `@app.prompt`，`app.render_prompt（）`，`await app.arender_prompt（）`，`app.list_prompts（）` |
| 中间件 | `app.add_middleware（）`，`@app.middleware` |
| 插件 | `app.register_plugin（）`，`Plugin`基类（可选） |
| 传输 | `app.run（）`（stdio），`app.run_http（）`（HTTP/SSE） |
---
---
# 官方BridgeMCP生态系统
## 框架
- **BridgeMCP**
https://github.com/Arsie-codes/bridgemcp
## 官方插件
- **bridgemcp-logging**
https://github.com/Arsie-codes/bridgemcp-logging
## 官方服务器
- **bridgemcp-server-weather**
https://github.com/Arsie-codes/bridgemcp-server-weather
更多官方插件和服务器目前正在开发中。
## 许可证
MIT - 版权所有（c）2026 Muhammad Arslan
