内容
# TUP MCP 服务器
> **Telepathy Universal Protocol — 模型上下文协议桥接**
>
> 跨组织的安全、零共享状态的AI-to-AI协作。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
---
## 🌐 什么是 TUP MCP 服务器？
**tup-mcp-server** 是一个开源的[模型上下文协议（MCP）](https://modelcontextprotocol.io/)服务器，允许来自不同组织的AI代理安全地协作，而无需共享系统提示、私有数据、模型权重或内部内存。
它实现了**Telepathy Universal Protocol（TUP）**，一种基于**零共享状态**原则的受管AI-to-AI通信标准。
### 关键特性
- 🔒 **零共享状态**：代理交换验证的语义向量（Intents），而非原始数据或提示。
- ⚡ **流式HTTP中继**：无状态中继服务器，使用分块HTTP流式传输 — 无WebSocket开销。
- 🧮 **四重数学验证**：条件数、往返检查、正交性和特征值稳定性检查。
- 🔁 **开放核心架构**：开箱即用，纯Python回退；可替换为高性能`telepathy-tup`引擎，以实现企业级速度。
- 🛡️ **DNS重绑定保护**：每个请求都验证Origin和Host头。
---
## 🏗️ 架构
```
[ 代理 A ] ──(MCP工具)──► [ tup-mcp-server A ] ──(HTTP)──► [ 中继 ] ──(HTTP)──► [ tup-mcp-server B ] ──(MCP)──► [ 代理 B ]
```
| 组件 | 许可证 | 描述 |
|---|---|---|
| `tup-mcp-server` | MIT | MCP服务器，暴露TUP工具给Claude和其他代理 |
| `relay.py` | MIT | 无状态流式HTTP中继，路由加密的Intents |
| `tup_core_fallback.py` | MIT | 纯Python参考TUP引擎（ActionSpec、Intent、Channel） |
| `telepathy-tup` | 专有 | 可选的高性能Cython核心（直接替换） |
---
## 🚀 快速开始
### 先决条件
- Python 3.10+
- pip
### 安装
```bash
# 克隆仓库
git clone https://github.com/telepathy-TUP/tup-mcp-server.git
cd tup-mcp-server
# 安装依赖
pip install -e ".[dev]"
```
### 运行中继服务器
```bash
python relay.py
# 中继启动于 http://localhost:8000
```
### 运行MCP服务器
```bash
python mcp_server.py
```
### 配置Claude Desktop
将`mcp_config.json`复制到Claude Desktop的配置文件目录中，或将以下内容添加到现有配置中：
```json
{
"mcpServers": {
"tup-mcp-server": {
"command": "python",
"args": ["path/to/mcp_server.py"],
"env": {
"TUP_RELAY_URL": "http://localhost:8000"
}
}
}
}
```
---
## 🔧 MCP工具
| 工具 | 描述 |
|---|---|
| `tup_connect` | 与中继服务器建立会话 |
| `tup_send_intent` | 构造、验证并发送语义意图 |
| `tup_get_pending_intents` | 从会话队列中检索接收到的Intents |
| `tup_get_session_status` | 返回通道状态、指标和回退状态 |
| `tup_transition_state` | 转换通道状态机 |
### 示例用法
```
1. tup_connect(relay_url="http://localhost:8000", session_id="collab-01", role="agent_a", partner_role="agent_b")
2. tup_send_intent(session_id="collab-01", vector=[0.5, 0.3, -0.1], operation="ALIGN", direction="FORWARD", cardinality=3, output_dimensions=128)
3. tup_get_pending_intents(session_id="collab-01")
4. tup_get_session_status(session_id="collab-01")
```
---
## 🧮 数学验证
回退核心对变换矩阵实施严格的**四重验证**：
1. **条件数**：`numpy.linalg.cond(A) ≤ 10¹⁰`
2. **往返检查**：`A × A⁻¹ ≈ I`，容差`1e-8`
3. **正交性检查**：`A × Aᵀ ≈ I`（范数保持优化）
4. **特征值稳定性**：`|λ| ≤ 1`，所有特征值（防止发散）
---
## 🧪 运行测试
```bash
python -m pytest -v
```
所有16个测试涵盖：
- `test_fallback_compatibility.py` — 核心数学、状态机、哈希完整性
- `test_mcp_tools.py` — MCP工具注册、矩阵拒绝、意图生命周期
- `test_relay_flow.py` — DNS重绑定保护、意图路由、会话管理
---
## 📂 项目结构
```
tup-mcp-server/
├── pyproject.toml # 包配置和依赖
├── mcp_config.json # 示例Claude Desktop配置
├── mcp_server.py # MCP服务器（FastMCP + 动态回退）
├── relay.py # 无状态流式HTTP中继（FastAPI）
├── tup_core_fallback.py # 纯Python TUP引擎（MIT）
├── README.md # 此文件
└── tests/
├── test_fallback_compatibility.py
├── test_mcp_tools.py
└── test_relay_flow.py
```
---
## 📜 许可证
该项目在**MIT许可证**下许可。有关详细信息，请参见[LICENSE](LICENSE)。
可选的高性能引擎`telepathy-tup`是专有的，并具有商业许可证。
