Content
# TUP MCP Server
> **Telepathy Universal Protocol — Model Context Protocol Bridge**
>
> Secure, zero-shared-state AI-to-AI collaboration across organizations.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
---
## 🌐 What is TUP MCP Server?
**tup-mcp-server** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI agents from different organizations to collaborate securely — without sharing system prompts, private data, model weights, or internal memory.
It implements the **Telepathy Universal Protocol (TUP)**, a governed AI-to-AI communication standard built on the principle of **Zero-Shared-State**.
### Key Features
- 🔒 **Zero-Shared-State**: Agents exchange validated semantic vectors (Intents), never raw data or prompts.
- ⚡ **Streamable HTTP Relay**: Stateless relay server using chunked HTTP streaming — no WebSocket overhead.
- 🧮 **4-Fold Mathematical Validation**: Condition number, round-trip, orthogonality, and eigenvalue stability checks.
- 🔁 **Open Core Architecture**: Works out-of-the-box with a pure-Python fallback; drops in the high-performance `telepathy-tup` engine for enterprise speed.
- 🛡️ **DNS Rebinding Protection**: Origin and Host header validation on every request.
---
## 🏗️ Architecture
```
[ Agent A ] ──(MCP Tool)──► [ tup-mcp-server A ] ──(HTTP)──► [ relay ] ──(HTTP)──► [ tup-mcp-server B ] ──(MCP)──► [ Agent B ]
```
| Component | License | Description |
|---|---|---|
| `tup-mcp-server` | MIT | MCP server exposing TUP tools to Claude and other agents |
| `relay.py` | MIT | Stateless Streamable HTTP relay routing encrypted intents |
| `tup_core_fallback.py` | MIT | Pure-Python reference TUP engine (ActionSpec, Intent, Channel) |
| `telepathy-tup` | Proprietary | Optional high-performance Cython core (drop-in replacement) |
---
## 🚀 Quick Start
### Prerequisites
- Python 3.10+
- pip
### Installation
```bash
# Clone the repository
git clone https://github.com/telepathy-TUP/tup-mcp-server.git
cd tup-mcp-server
# Install dependencies
pip install -e ".[dev]"
```
### Run the Relay Server
```bash
python relay.py
# Relay starts at http://localhost:8000
```
### Run the MCP Server
```bash
python mcp_server.py
```
### Configure Claude Desktop
Copy `mcp_config.json` into your Claude Desktop configuration directory, or add the following to your existing config:
```json
{
"mcpServers": {
"tup-mcp-server": {
"command": "python",
"args": ["path/to/mcp_server.py"],
"env": {
"TUP_RELAY_URL": "http://localhost:8000"
}
}
}
}
```
---
## 🔧 MCP Tools
| Tool | Description |
|---|---|
| `tup_connect` | Establishes a session with the relay server |
| `tup_send_intent` | Constructs, validates, and sends a semantic intent |
| `tup_get_pending_intents` | Retrieves received intents from the session queue |
| `tup_get_session_status` | Returns channel state, metrics, and fallback status |
| `tup_transition_state` | Transitions the channel state machine |
### Example Usage
```
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")
```
---
## 🧮 Mathematical Validation
The fallback core implements a rigorous **4-fold validation** on transformation matrices:
1. **Condition Number**: `numpy.linalg.cond(A) ≤ 10¹⁰`
2. **Round-Trip Check**: `A × A⁻¹ ≈ I` with tolerance `1e-8`
3. **Orthogonality Check**: `A × Aᵀ ≈ I` (norm-preserving optimization)
4. **Eigenvalue Stability**: `|λ| ≤ 1` for all eigenvalues (prevents divergence)
---
## 🧪 Running Tests
```bash
python -m pytest -v
```
All 16 tests cover:
- `test_fallback_compatibility.py` — Core math, state machine, hash integrity
- `test_mcp_tools.py` — MCP tool registration, matrix rejection, intent lifecycle
- `test_relay_flow.py` — DNS rebinding protection, intent routing, session management
---
## 📂 Project Structure
```
tup-mcp-server/
├── pyproject.toml # Package configuration & dependencies
├── mcp_config.json # Example Claude Desktop config
├── mcp_server.py # MCP server (FastMCP + dynamic fallback)
├── relay.py # Stateless Streamable HTTP relay (FastAPI)
├── tup_core_fallback.py # Pure-Python TUP engine (MIT)
├── README.md # This file
└── tests/
├── test_fallback_compatibility.py
├── test_mcp_tools.py
└── test_relay_flow.py
```
---
## 📜 License
This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
The optional high-performance engine `telepathy-tup` is proprietary and commercially licensed.
---
---
# TUP MCP Server (Español)
> **Telepathy Universal Protocol — Puente de Protocolo de Contexto de Modelo**
>
> Colaboración segura entre agentes de IA sin compartir estado.
---
## 🌐 ¿Qué es TUP MCP Server?
**tup-mcp-server** es un servidor de código abierto compatible con el [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) que permite a agentes de IA de distintas organizaciones colaborar de forma segura — sin compartir prompts del sistema, datos privados, pesos de modelo ni memoria interna.
Implementa el **Telepathy Universal Protocol (TUP)**, un estándar de comunicación gobernada IA-a-IA construido sobre el principio de **Cero Estado Compartido (Zero-Shared-State)**.
### Características Principales
- 🔒 **Cero Estado Compartido**: Los agentes intercambian vectores semánticos validados (Intents), nunca datos crudos ni prompts.
- ⚡ **Relay Streamable HTTP**: Servidor de retransmisión sin estado usando streaming HTTP chunked — sin sobrecarga de WebSocket.
- 🧮 **Validación Matemática de 4 Niveles**: Número de condición, round-trip, ortogonalidad y estabilidad de autovalores.
- 🔁 **Arquitectura Open Core**: Funciona out-of-the-box con un fallback en Python puro; acepta el motor de alto rendimiento `telepathy-tup` como reemplazo directo para velocidad empresarial.
- 🛡️ **Protección contra DNS Rebinding**: Validación de headers Origin y Host en cada solicitud.
---
## 🚀 Inicio Rápido
### Requisitos
- Python 3.10+
- pip
### Instalación
```bash
# Clonar el repositorio
git clone https://github.com/telepathy-TUP/tup-mcp-server.git
cd tup-mcp-server
# Instalar dependencias
pip install -e ".[dev]"
```
### Ejecutar el Relay
```bash
python relay.py
# El relay se inicia en http://localhost:8000
```
### Ejecutar el Servidor MCP
```bash
python mcp_server.py
```
### Configurar Claude Desktop
Copie `mcp_config.json` al directorio de configuración de Claude Desktop, o agregue lo siguiente a su configuración existente:
```json
{
"mcpServers": {
"tup-mcp-server": {
"command": "python",
"args": ["ruta/a/mcp_server.py"],
"env": {
"TUP_RELAY_URL": "http://localhost:8000"
}
}
}
}
```
---
## 🔧 Herramientas MCP
| Herramienta | Descripción |
|---|---|
| `tup_connect` | Establece una sesión con el servidor relay |
| `tup_send_intent` | Construye, valida y envía una intención semántica |
| `tup_get_pending_intents` | Recupera intents recibidos de la cola de sesión |
| `tup_get_session_status` | Devuelve estado del canal, métricas e indicador de fallback |
| `tup_transition_state` | Transiciona la máquina de estados del canal |
---
## 🧪 Ejecutar Pruebas
```bash
python -m pytest -v
```
Las 16 pruebas cubren:
- `test_fallback_compatibility.py` — Matemáticas del core, máquina de estados, integridad de hashes
- `test_mcp_tools.py` — Registro de herramientas MCP, rechazo de matrices, ciclo de vida de intents
- `test_relay_flow.py` — Protección DNS rebinding, enrutamiento de intents, gestión de sesiones
---
## 📜 Licencia
Este proyecto está licenciado bajo la **Licencia MIT**. Ver [LICENSE](LICENSE) para detalles.
El motor de alto rendimiento opcional `telepathy-tup` es propietario y tiene licencia comercial.
