使用说明

在Cloudflare上构建远程MCP服务器（使用JWT身份验证）

此示例允许您在Cloudflare Workers上部署具有JWT承载令牌身份验证的远程MCP服务器。服务器使用简化的身份验证机制以提高可维护性。

开始：

这将把您的MCP服务器部署到以下URL： remote-mcp-server-authless.<your-account>.workers.dev/sse

或者，您可以使用下面的命令行在本地计算机上创建远程MCP服务器：

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless

🔐 JWT身份验证配置

此MCP服务器使用简化的JWT承载令牌身份验证机制，以提高安全性和可维护性。

环境变量

变量	描述	示例
`JWT_SECRET`	JWT令牌验证密钥	`your-super-secure-jwt-secret`

设置身份验证

配置JWT密钥以进行令牌验证：

# Set JWT secret
wrangler secret put JWT_SECRET
# Enter: your-super-secure-jwt-secret

身份验证方法

在Authorization标头中包含JWT令牌：

curl -H "Authorization: Bearer your-jwt-token" https://your-worker.workers.dev/sse

生成JWT令牌

使用附带的实用程序生成JWT令牌：

# Generate a JWT token
npm run generate-jwt

或者以编程方式：

import { generateJWT } from './src/auth-utils.js';

const payload = {
  userId: 'user123',
  username: 'john_doe',
  roles: ['user']
};

const token = await generateJWT(payload, 'your-jwt-secret', 3600); // 1 hour expiry
console.log('Generated JWT:', token);

自定义您的MCP服务器

添加您自己的工具在MCP服务器中，定义 init() 方法 src/index.ts 使用 this.server.tool(...).

连接到Cloudflare AI游乐场

您可以从Cloudflare AI Playground连接到您的MCP服务器，这是一个远程MCP客户端：

首选https://playground.ai.cloudflare.com/
输入您部署的MCP服务器URL(remote-mcp-server-authless.<your-account>.workers.dev/sse)
重要提示： 添加身份验证标头： Authorization: Bearer your-jwt-token
现在，您可以直接在操场上使用MCP工具！

健康检查端点

服务器包含一个不需要身份验证的健康检查端点：

curl https://mcp.123648.xyz/health

答复：

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "service": "MCP Server with JWT Auth"
}

将Claude Desktop连接到您的MCP服务器

您还可以使用以下命令从本地MCP客户端连接到远程MCP服务器 mcp远程代理.

要从Claude Desktop连接到MCP服务器，请按照以下步骤操作 Anthropic的快速入门在Claude Desktop中，转到“设置”>“开发人员”>“编辑配置”。

无身份验证（开发）

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

JWT认证（生产）

{
  "mcpServers": {
    "calculator": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote-mcp-server-authless.your-account.workers.dev/sse"
      ],
      "env": {
        "MCP_REMOTE_HEADERS": "{\"Authorization\": \"Bearer your-jwt-token\"}"
      }
    }
  }
}

重新启动Claude，您应该会看到工具可用。

🔧 开发和测试

地方发展

克隆存储库
安装依赖项： npm install
在中设置环境变量 .dev.vars 文件：
```
JWT_SECRET=your-local-jwt-secret
```
启动开发服务器： npm run dev

测试身份验证

测试运行状况终结点（无需身份验证）：

curl http://localhost:8787/health

使用JWT令牌进行测试：

curl -H "Authorization: Bearer your-jwt-token" http://localhost:8787/sse

使用无效的JWT令牌进行测试（应返回401）：

curl -H "Authorization: Bearer invalid-token" http://localhost:8787/sse

安全最佳实践

使用强大的JWT秘密：生成具有足够长度（64+个字符）的加密安全JWT密钥
定期轮换秘密：为生产环境实施秘密轮换策略
使用HTTPS：始终在生产中使用HTTPS来保护传输中的身份验证令牌
监控访问：定期查看日志，查看可疑的身份验证尝试
环境隔离：在开发、暂存和生产环境中使用不同的机密
令牌到期：为JWT令牌设置适当的过期时间

故障排除

身份验证失败错误：

验证您的JWT令牌是否正确且未过期
检查授权标头的格式是否正确(Authorization: Bearer <token>)
确保JWT_SECRET环境变量设置正确
检查服务器日志以获取详细的错误消息

令牌问题：

使用生成新的JWT令牌 npm run generate-jwt
验证令牌有效负载是否包含所需字段
检查令牌过期时间

🚀 交互式反馈系统（v2.0）

本 MCP 服务器现已升级为完整的交互式反馈收集系统，提供以下新功能：

✨ 新增功能

📋 完整的反馈 API

创建会话: POST /api/feedback/create - 创建新的反馈会话
获取状态: GET /api/feedback/{sessionId}/status - 查询会话状态
提交反馈: POST /api/feedback/{sessionId}/submit - 提交用户反馈
获取结果: GET /api/feedback/{sessionId}/result - 获取反馈结果

🎨 响应式 Web 界面

反馈页面: GET /feedback/{sessionId} - 用户友好的反馈界面
主题支持: 支持明暗主题切换 (?theme=dark|light)
多语言: 支持中英文切换 (?lang=zh|en)
响应式设计: 适配桌面和移动设备

⚡ WebSocket 实时通信

实时状态更新: 会话状态变化时自动推送
多端同步: 支持多个客户端同时监听
App 集成: 支持移动应用和 Web 应用连接

🛠️ 增强的 MCP 工具

交互式反馈: 创建反馈会话
get_feedback_result: 获取反馈结果
check_feedback_status: 检查会话状态

📖 使用示例

1. 通过 MCP 工具创建反馈会话

// 在 Claude Desktop 或其他 MCP 客户端中使用
{
  "tool": "interactive_feedback",
  "arguments": {
    "message": "请对我们的服务进行评价",
    "predefinedOptions": ["非常满意", "满意", "一般", "不满意"],
    "timeout": 600,
    "metadata": {
      "source": "customer-service",
      "category": "satisfaction-survey"
    }
  }
}

2. 通过 API 创建反馈会话

curl -X POST https://your-worker.workers.dev/api/feedback/create \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请选择您喜欢的功能",
    "predefinedOptions": ["功能A", "功能B", "功能C"],
    "timeout": 300
  }'

3. 用户访问反馈界面

用户访问返回的 feedbackUrl，例如：

https://your-worker.workers.dev/feedback/123e4567-e89b-12d3-a456-426614174000?theme=dark&lang=zh

4. 获取反馈结果

curl -H "Authorization: Bearer your-jwt-token" \
  https://your-worker.workers.dev/api/feedback/123e4567-e89b-12d3-a456-426614174000/result

5. WebSocket 实时监听

const ws = new WebSocket('wss://your-worker.workers.dev/ws/123e4567-e89b-12d3-a456-426614174000?apiKey=your-api-key&clientType=web');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('收到消息:', message);

  switch (message.type) {
    case 'connection_established':
      console.log('连接已建立');
      break;
    case 'session_status_changed':
      console.log('状态变化:', message.data);
      break;
    case 'feedback_submitted':
      console.log('反馈已提交:', message.data);
      break;
  }
};

🧪 测试

运行完整的测试套件：

# 安装测试依赖
npm install

# 运行测试
node test/interactive-feedback-tests.js

测试包括：

✅ 健康检查
✅ 创建反馈会话
✅ 获取会话状态
✅ 提交反馈
✅ 获取反馈结果
✅ 反馈界面访问
✅ WebSocket 连接

🔧 配置选项

环境变量

变量	描述	默认值
`JWT_SECRET`	JWT 令牌密钥	必需
`OAUTH_KV`	KV 存储绑定	必需

会话配置

默认超时: 300 秒 (5 分钟)
最大超时: 3600 秒 (1 小时)
最大消息长度: 1000 字符
最大选项数量: 10 个
最大选项长度: 100 字符

🏗️ 架构说明

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   Web Browser   │    │  Mobile App     │
│  (Claude etc.)  │    │                 │    │                 │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │ JWT Auth             │ No Auth              │ WebSocket
          │                      │                      │
          ▼                      ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Cloudflare Worker                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ MCP Handler │  │ API Handler │  │   WebSocket Handler     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                           │                                     │
│  ┌─────────────────────────┼─────────────────────────────────┐  │
│  │              Feedback Service                            │  │
│  └─────────────────────────┼─────────────────────────────────┘  │
└────────────────────────────┼───────────────────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   KV Storage    │
                    │   (Sessions)    │
                    └─────────────────┘

📚 API 文档

详细的 API 文档请参考 docs/api-design.md 文件。

🔄 版本历史

v2.0.0版本: 完整的交互式反馈系统
- 新增 RESTful API
- 响应式 Web 界面
- WebSocket 实时通信
- 增强的 MCP 工具
- 完整的测试套件
v1.0.0: 基础 MCP 服务器
- JWT 认证
- 基础反馈工具
- KV 存储

使用说明

在Cloudflare上构建远程MCP服务器（使用JWT身份验证）

开始：

🔐 JWT身份验证配置

环境变量

设置身份验证

身份验证方法

生成JWT令牌

自定义您的MCP服务器

连接到Cloudflare AI游乐场

健康检查端点

将Claude Desktop连接到您的MCP服务器

无身份验证（开发）

JWT认证（生产）

🔧 开发和测试

地方发展

测试身份验证

安全最佳实践

故障排除

🚀 交互式反馈系统（v2.0）

✨ 新增功能

📋 完整的反馈 API

🎨 响应式 Web 界面

⚡ WebSocket 实时通信

🛠️ 增强的 MCP 工具

📖 使用示例

1. 通过 MCP 工具创建反馈会话

2. 通过 API 创建反馈会话

3. 用户访问反馈界面

4. 获取反馈结果

5. WebSocket 实时监听

🧪 测试

🔧 配置选项

环境变量

会话配置

🏗️ 架构说明

📚 API 文档

🔄 版本历史

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器