Banbury Cloud MCP Server

Banbury Cloud MCP 服务

一个模型上下文协议（MCP）服务，为大模型和 AI 应用提供访问 Banbury 后端服务的能力。

快速开始

前端集成（HTTP 模式）

# Run on default port 3001
./run-http.sh

# Run on custom port
./run-http.sh 8080

然后添加到前端 .env：

REACT_APP_MCP_SERVER_URL=http://localhost:3001

Claude Desktop（Stdio 模式）

# Default stdio mode
./run.sh

添加到 Claude Desktop 配置：

{
  "mcpServers": {
    "banbury-mcp": {
      "command": "/path/to/banbury-mcp-server/run.sh"
    }
  }
}

传输模式

HTTP 传输

• 用途：前端集成、Web 应用、API 访问
• 端口：可配置（默认：3001）
• 端点：
  • POST /tool - 执行 MCP 工具
  • GET /health - 服务健康状态和信息

Stdio 传输

• 用途：Claude Desktop、直接进程通信
• 通信方式：stdin/stdout
• 集成方式：MCP 客户端库

环境变量

# Transport mode: 'http' or 'stdio' (default: stdio)
export MCP_TRANSPORT=http

# HTTP port (default: 3001)  
export MCP_HTTP_PORT=8080

# Banbury environment: 'dev' or 'prod' (default: dev)
export BANBURY_ENV=dev

可用工具

身份验证

• banbury-login - 使用 Banbury 凭据进行身份验证

设备管理

• banbury-get-device-info - 获取设备信息
• banbury-update-device - 更新设备数据
• banbury-declare-online - 声明设备在线

文件管理

• banbury-get-files - 从指定路径获取文件
• banbury-get-scanned-folders - 获取已扫描的文件夹列表

任务管理

• banbury-get-sessions - 获取用户会话
• banbury-add-task - 添加新任务

模型管理

• banbury-add-model - 将模型添加到设备

实用工具

• add - 简单加法（测试用）
• get-joke - 随机笑话（娱乐用）

使用示例

HTTP 模式

# Health check
curl http://localhost:3001/health

# Get a joke
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "get-joke", "parameters": {}}'

# Login to Banbury  
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "banbury-login", 
    "parameters": {
      "username": "your-username",
      "password": "your-password",
      "environment": "dev"
    }
  }'

# Get device info using Authorization header
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

# Get device info using X-API-Key and Authorization Bearer headers
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -H "X-API-Key: your-mcp-server-api-key" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

# Get device info using parameters (legacy method)
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "token": "your-auth-token", 
      "apiKey": "your-api-key",
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

前端集成

MCP 服务可与 Banbury 前端无缝集成：

1. 设置环境变量：REACT_APP_MCP_SERVER_URL=http://localhost:3001
2. 前端会自动使用已存储的 Banbury 凭据
3. 所有请求都会自动包含身份验证标头：
   • X-Auth-Token：用户的 Banbury 令牌
   • X-Username：用户的 Banbury 用户名
   • Authorization：MCP 服务 API 密钥（如果已配置）
4. AI 对话可以自然地调用 Banbury 工具
5. 实时状态指示器会显示连接和身份验证状态

开发

项目结构

banbury-mcp-server/
├── main.ts           # Main server code
├── run.sh           # Stdio mode runner
├── run-http.sh      # HTTP mode runner  
├── package.json     # Dependencies
└── README.md        # Documentation

添加新工具

1. 在 main.ts 中添加工具定义：

server.tool("my-new-tool", {
  token: z.string(),
  my_param: z.string(),
  environment: z.enum(['dev', 'prod']).default('dev')
}, async ({ token, my_param, environment }) => {
  // Implementation
});

2. 添加 HTTP 处理器分支：

case 'my-new-tool':
  result = await handleMyNewTool(parameters);
  break;

测试

# Install dependencies
npm install

# Run in development
npm run dev

# Type checking
npm run type-check

安全性

• 所有 Banbury API 调用都需要身份验证令牌
• 已启用 CORS，以支持前端集成
• 不会记录或缓存敏感数据
• 令牌验证由 Banbury 后端处理

故障排除

连接问题

• 确认服务正在运行：curl http://localhost:3001/health
• 检查 HTTP 模式的防火墙设置
• 确保可以访问 Banbury 后端 URL

身份验证错误

• 确认 Banbury 凭据有效
• 检查令牌是否已过期
• 确保选择了正确的环境（dev/prod）

工具执行错误

• 查看服务日志中的详细错误消息
• 确认已提供必需参数
• 确保令牌具有适当的权限

如需更多帮助，请查看服务日志或 Banbury 前端集成指南。

身份验证方法

MCP 服务支持多种身份验证方法，优先级如下：

1. Authorization 标头：Authorization: Bearer <token>（主要方式，与 axios 全局标头一致）
2. X-Auth-Token 标头：X-Auth-Token: <token>（备用方式）
3. X-API-Key 标头：X-API-Key: <api-key>（用于 MCP 服务 API 密钥）
4. X-Username 标头：X-Username: <username>（用于用户上下文）
5. 请求参数：在参数对象中包含 token 和/或 apiKey（旧版方式）

前端会自动通过 Authorization: Bearer <token> 标头发送 Banbury 用户令牌，遵循与 axios 全局标头实现相同的模式。