项目概述
此项目是一个Cloudflare Worker应用程序,它实现了一个用于控制Mapbox映射的模型控制协议(MCP)服务器。该应用程序使用:
- TypeScript用于类型安全
- API路由的Hono
- OpenAI和Anthropic的Bedrock SDK用于AI模型访问
- 用于交互式地图的Mapbox GL JS
- MCP客户端连接的服务器发送事件(SSE)
入门指南
在开始之前,您需要一个Cloudflare帐户。
1.注册Cloudflare
如果你还没有, 注册一个免费的Cloudflare帐户.
2.安装牧马人
Wrangler是Cloudflare Workers的命令行界面。你可以使用npm安装它:```bash
npm install -g wrangler
安装后,您需要登录您的Cloudflare帐户:```bash
wrangler login
这将打开一个浏览器窗口,以便与Cloudflare进行身份验证。一旦通过身份验证,您就可以继续设置项目。
开发环境
命令```bash
Install dependencies
npm install
Start development server
npm run dev
Build the project
npm run build
Deploy to Cloudflare (default environment)
npm run deploy
Deploy to staging environment
npm run deploy:staging
Deploy to production environment
npm run deploy:production
Type checking
npm run lint
### 环境变量
需要在Cloudflare Worker中设置以下环境变量:
- `OPENAI_API_KEY`:您的OpenAI API密钥
- `ANTHROPIC_API_KEY`:您的Anthropic API密钥(可选)
- `MAPBOX_ACCESS_TOKEN`:您的Mapbox访问令牌
要设置部署密钥,请执行以下操作:```bash
wrangler secret put OPENAI_API_KEY
wrangler secret put MAPBOX_ACCESS_TOKEN
代码架构
核心组件
- MCP服务器(
src/services/mcp-server.ts)
- 处理与AI模型的通信
- 处理MCP请求和工具调用
- 同时支持OpenAI和Anthropic模型
- 地图框工具(
src/services/mapbox-tools.ts)
- 定义用于Mapbox地图操作的MCP工具
- 包括用于初始化贴图、移动、添加/删除图层等的工具。
- API路线(
src/index.ts)
- 为MCP服务器实现Hono路由
- 处理用于聊天和工具结果处理的API端点
- 为MCP客户端连接提供SSE端点
- 公开工具列表和调用端点
- 前端(
public/)
- HTML、CSS和客户端JavaScript
- 实现地图界面和聊天功能
- 与MCP服务器通信
数据流
- Web用户界面: 用户通过聊天界面发送消息
- 消息被发送到MCP服务器
- MCP服务器将消息转发给AI模型
- 工具调用在地图上执行
- 结果显示给用户
- MCP客户端: 外部AI助手连接到SSE端点
- 客户端与建立SSE连接
/sse - 客户端通过以下方式获取可用工具
/tools - 客户端通过以下方式调用工具
/invoke - 结果返回给客户端
部署
标准部署```bash
npm run deploy
这将把你的worker部署到 `map-mcp-tools.your-worker-subdomain.workers.dev`.
### 特定于环境的部署```bash
# Deploy to staging
npm run deploy:staging
# Deploy to production
npm run deploy:production
与MCP客户端连接
部署后,您的MCP服务器将可在以下位置访问:
- SSE 端点 :
https://map-mcp-tools.your-worker-subdomain.workers.dev/sse - 工具端点:
https://map-mcp-tools.your-worker-subdomain.workers.dev/tools - 调用终结点:
https://map-mcp-tools.your-worker-subdomain.workers.dev/invoke
您可以使用连接到MCP服务器 MCP检查员 或其他MCP客户端。
重要提示
- 此应用程序实现了模型控制协议(MCP)模式,如中所述 Cloudflare的MCP服务器指南
- MCP服务器允许AI模型通过一组预定义的工具来控制Mapbox地图
- 该应用程序被设计为部署为Cloudflare Worker(可以适应具有相同模式的任何环境)
- 可以按照Cloudflare的OAuth集成示例添加身份验证
