研究与期望——锁箱MCP服务器
Serveur MCP（模型上下文协议）启动模式 HTTP流式传输 公开API 研究与欲望 --章节 锁箱装置, 锁定会话 和 锁定模板.
服务器在Docker容器中运行，并在途中响应 /mcp.
______________________________________________________________________
目录
______________________________________________________________________
建筑
┌─────────────────┐ JSON-RPC / HTTP ┌──────────────────────┐
│ Client MCP │ ─────────────────────────────▶ │ MCP Server (Python) │
│ (Claude, etc.) │ Bearer MCP_AUTH_TOKEN │ /mcp │
└─────────────────┘ └──────────┬───────────┘
│
Bearer RD_API_TOKEN
│
▼
┌──────────────────────┐
│ R&D Dashboard API │
│ /api/v1/lkbx/... │
└──────────────────────┘- 运输 ：HTTP流式传输（JSON-RPC 2.0 sur HTTP）
- 认证MCP ：不记名代币(
MCP_AUTH_TOKEN）由ASGI中间件验证 - 认证研发API ：不记名代币(
RD_API_TOKEN）每次调用Research&Desire API时发送 - 软件开发工具包 : MCP Python SDK (
FastMCP)
______________________________________________________________________
MCP工具可用
锁箱装置
| 工具 | 描述 | 设置 |
|---|---|---|
list_lockbox_devices | 列出帐户中的所有锁箱设备 | limit （int，1-100，默认值50）， offset （int，默认值0） |
get_lockbox_device | 获取锁箱设备的详细信息 | device_id （INT，必填） |
锁定会话
| 工具 | 描述 | 设置 |
|---|---|---|
list_lock_sessions | 列出所有锁定会话 | limit （int，1-100，默认值50）， offset （int，默认值0） |
get_lock_session | 按ID获取会话详细信息 | session_id （INT，必填） |
get_active_lock_session | 获取当前活动会话 | - |
get_latest_lock_session | 获取最近的会话 | - |
lock_or_unlock | 开始锁定或解锁 | action （“锁定”/“解锁”，必填项）， lock_settings_id （int）， keyholder_ids （list\[int\]）， target_user_id （int）， is_test_lock （bool） |
modify_active_lock_session | 更改活动会话的持续时间 | duration （int，必需，以秒为单位）， target_user_id （int） |
锁定模板
| 工具 | 描述 | 设置 |
|---|---|---|
list_lock_templates | 列出所有锁定模板 | limit （int，1-100，默认值50）， offset （int，默认值0） |
get_lock_template | 按ID获取模板的详细信息 | template_id （INT，必填） |
get_active_lock_template | 获取活动会话的模板 | - |
______________________________________________________________________
环境变量
| 变量 | 必需 | 描述 | 默认值 |
|---|---|---|---|
MCP_AUTH_TOKEN | 推荐 | 令牌承载器验证MCP客户端 | *（视频=认证）* |
RD_API_TOKEN | 是 | Research&Desire API的代币承载器（需要超订阅） | - |
RD_API_BASE_URL | 非 | API研发基础URL | https://dashboard.researchanddesire.com/api/v1 |
RD_SERVER_PORT | 否 | 服务器侦听端口 | 3000 |
RD_SERVER_HOST | 否 | 服务器侦听地址 | 0.0.0.0 |
备注 ：与Research&Desire相关的所有变量均以RD_MCP令牌使用名称MCP_AUTH_TOKEN.
______________________________________________________________________
使用Docker快速启动
1.塑造形象
docker build -t rd-mcp-server .2.集装箱的发射
docker run -d \
--name rd-mcp-server \
-p 3000:3000 \
-e MCP_AUTH_TOKEN="votre-token-mcp-secret" \
-e RD_API_TOKEN="votre-token-api-rd" \
-e RD_API_BASE_URL="https://dashboard.researchanddesire.com/api/v1" \
-e RD_SERVER_PORT="3000" \
rd-mcp-server3.核查
# Envoi d'une requête initialize MCP
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer votre-token-mcp-secret" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": { "name": "test-client", "version": "1.0.0" }
}
}'______________________________________________________________________
Docker Compose
文件 docker-compose.yml 提供。创建文件 .env 在项目的根源（参见 .env.example) :
cp .env.example .env
# Éditez .env avec vos vrais tokens然后启动：
docker compose up -d --build要停止：
docker compose down______________________________________________________________________
客户端MCP配置
克劳德桌面/克劳德代码
将此配置添加到MCP设置文件：
{
"mcpServers": {
"rd-lockbox": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp",
"headers": {
"Authorization": "Bearer votre-token-mcp-secret"
}
}
}
}使用curl调用示例
# Lister les outils disponibles
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer votre-token-mcp-secret" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}'
# Appeler un outil
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer votre-token-mcp-secret" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "list_lockbox_devices",
"arguments": { "limit": 10, "offset": 0 }
}
}'______________________________________________________________________
MCP方案
服务器实现标准 MCP（模型上下文协议） 完整：
| 方法 | 描述 |
|---|---|
initialize | 使用服务器功能响应客户端的初始化请求 |
tools/list | 列出11个可用的工具及其JSON模式 |
tools/call | 使用提供的参数运行请求的工具并返回结果 |
所有答案都遵循以下格式： JSON-RPC 2.0 :
{
"jsonrpc": "2.0",
"id": 1,
"result": { "..." }
}______________________________________________________________________
安全
- 双重身份验证 ：MCP服务器受其自己的令牌保护（
MCP_AUTH_TOKEN），独立于研发API令牌（RD_API_TOKEN) - 秘密的分离 ：令牌是通过Docker环境变量注入的，从不在源代码中
- Pas d'auth=警告 ：Si
MCP_AUTH_TOKEN未定义，服务器在没有身份验证的情况下启动，但在日志中显示警告 - 错误管理 ：捕获研发API错误并干净地返回MCP客户端（无服务器崩溃）
______________________________________________________________________
项目结构
rd-mcp-server/
├── Dockerfile # Image Docker (Python 3.12-slim)
├── docker-compose.yml # Orchestration avec variables d'environnement
├── requirements.txt # Dépendances Python (mcp, httpx, uvicorn)
├── .env.example # Modèle de fichier de variables d'environnement
├── .dockerignore # Fichiers exclus du build Docker
├── README.md # Cette documentation
└── src/
├── __init__.py
├── main.py # Point d'entrée — crée l'app ASGI avec auth middleware
├── config.py # Configuration depuis les variables d'environnement
├── auth.py # Middleware Bearer token pour le serveur MCP
├── rd_client.py # Client HTTP async pour l'API Research & Desire
└── server.py # Serveur FastMCP — définition des 11 outils