colloid (Dd Colloid Inc)

胶体

*均匀分布的MCP网关*

API网关 模型上下文协议（MCP），用Rust写的。

什么是胶体？

Colloid位于LLM应用程序和MCP服务器之间，提供集中管理、安全和编排。就像化学中的胶体一样，粒子均匀地分布在介质中，胶体将您的请求无缝地分布在多个MCP服务器上。

┌─────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Clients   │     │     Colloid     │     │  MCP Servers    │
│             │     │                 │     │                 │
│ Claude      │────>│ • Authenticate  │────>│ GitHub MCP      │
│ Desktop     │     │ • Authorize     │     │ Slack MCP       │
│             │` |

下面的示例使用API密钥身份验证。

### 初始化会话

curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-secure-api-key-at-least-32-characters-long" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-app", "version": "1.0.0" } } }'

### 列出工具

curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-secure-api-key-at-least-32-characters-long" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

### 调用工具

工具按服务器ID命名(`server:tool`):

curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-secure-api-key-at-least-32-characters-long" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "github:create_issue", "arguments": { "repo": "owner/repo", "title": "Bug report" } } }'

### 临时请求

使用 `X-Idempotency-Key` 用于安全重试的标头：

curl -X POST http://localhost:3001/mcp \ -H "X-API-Key: your-api-key-at-least-32-characters-long" \ -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", ...}'

### 服务器发送事件（SSE）

对于流媒体响应：

curl -N http://localhost:3001/mcp/sse \ -H "X-API-Key: your-secure-api-key-at-least-32-characters-long"

## API终点

|端点|方法|身份验证|描述|
|----------|--------|------|-------------|
| `/health` |GET |否|健康检查|
| `/servers` |GET |否|列出已注册的MCP服务器|
| `/config` |GET|否|列出可用的客户端配置|
| `/config/{client}` |GET |否|获取特定于客户端的配置|
| `/ui` |GET |否| Web用户界面|
| `/mcp` |POST |是|MCP JSON-RPC端点|
| `/mcp/sse` |GET|是|服务器发送的事件流|
| `/v1/mcp` |POST |是|版本化MCP端点|
| `/v1/mcp/sse` |GET|是|版本化SSE端点|

## 客户端配置

Colloid为流行的MCP客户端提供自动生成的配置：

### 克劳德桌面

curl http://localhost:3001/config/claude-desktop

退货：

{ "mcpServers": { "colloid": { "url": "http://localhost:3001/mcp/sse", "transport": "sse" } } }

### 光标

curl http://localhost:3001/config/cursor

## 工具名称间距

|服务器|原始工具|网关工具|
|--------|--------------|--------------|
|github| `create_issue` | `github:create_issue` |
|松弛| `send_message` | `slack:send_message` |
|数据库| `query` | `database:query` |

## 安全

### API关键要求

- 最少32个字符（256位熵）
- 持续的时间比较，防止计时攻击
- 在生产过程中，需要API密钥（无默认密钥）

### 安全标头

所有响应都包含安全标头：

- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Content-Security-Policy: default-src 'none'`
- `Cache-Control: no-store`

### SSRF保护

远程运行时验证URL以防止SSRF攻击：

- 阻止私有IP地址（10.x、192.168.x、127.x等）
- 阻止云元数据端点（169.254.169.254）
- 只允许http/https方案

### 请求限制

- 最大机身尺寸：1MB
- 速率限制：可配置每个用户的限制

## 工作流

将多个工具调用链接到自动化工作流程中：

curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key-at-least-32-characters-long" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "workflows/list" }'

## 环境变量

|变量|描述|默认值|
|----------|-------------|---------|
| `RUST_LOG` |日志级别筛选器| `colloid=info` |
| `CONFIG_PATH` |配置文件路径| `config.yaml` |

## 文档

- [建筑.md](ARCHITECTURE.md) -系统设计和技术细节
- [CLAUDE.md](CLAUDE.md) -开发人员指南和代码模式
- [INDEX.md](INDEX.md) -文件索引

## 许可证

Apache许可证2.0

## 参考文献

- [MCP规范](https://modelcontextprotocol.io/specification/2025-06-18)
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification)