MCP Server

什么是 MCP？

MCP（Model Context Protocol）是一套标准化协议，让 AI 助手访问外部数据源与工具。文档站内置 MCP Server，经 /mcp 端点对外开放，Claude Code、Cursor、VS Code 等工具可直接连接，按对话上下文检索本库的组件信息、源码与用法示例。

服务为本组件库提供结构化访问，让 AI 工具更准确地理解并协助 @movk/mapbox 开发，访问地址为 https://mapbox.mhaibaraai.cn/mcp。

可用资源

MCP Server 提供以下可发现资源：

• resource://docs/components：浏览全部组件及其分类
• resource://docs/composables：浏览全部 composables 及其分类
• resource://docs/examples：浏览全部代码示例
• resource://docs/documentation-pages：浏览全部文档页面
• resource://docs/mapbox-conventions：本库声明式范式的硬约束（SSR、容器高度、omitUndefined、相机 v-model、图层生命周期等）
• resource://docs/basemap-styles：可用底图预设（Mapbox 官方样式与天地图图层类型 vec/img/ter）

在 Claude Code 等工具中可用 @ 引用这些资源。

可用工具

MCP Server 按类别提供以下工具：

搜索工具

• search-composables：按名称或描述搜索 composables，无参数时列出全部
• search-icons：在 Iconify 集合中搜索图标（默认 lucide），返回 i-{prefix}-{name} 格式名称

文档工具

• search-documentation：按标题、描述或 section 搜索文档页，无参数时列出全部
• get-documentation-page：按路径取页面内容，支持 headings 仅取指定 h2

组件工具

• get-component：取组件文档，支持 sections（usage / examples / api / theme / changelog）仅取部分
• get-component-metadata：取组件 props / slots / emits 元数据（轻量，无正文）

示例工具

• list-examples：列出全部示例
• get-example：取指定示例的实现代码

Mapbox 工具

• list-mapbox-components：按分类（core / layers / controls / effects / environment / extensions / composables / utils）列出全部能力，可按分类或关键词过滤
• convert-coordinates：在 WGS84 / GCJ02 / BD09 间转换坐标，支持单点或点数组
• get-layer-paint-schema：按图层 type（circle / line / fill / symbol / heatmap / fill-extrusion / raster）返回常用 paint / layout 键与最小脚手架

可用 Prompts

MCP Server 提供以下引导式 Prompt：

• find_component_for_usecase：按使用场景推荐合适的组件
• implement_component_with_props：基于文档与元数据生成组件实现
• build-mapbox-map：按任务描述组装一张地图，仅用文档中存在的组件并遵守本库约定

在支持 Prompt 的工具中可用 / 调用。

配置

MCP Server 采用 HTTP 传输，可在不同 AI 工具中接入，统一使用名称 movk-mapbox 与地址 https://mapbox.mhaibaraai.cn/mcp。

Claude Code

用 CLI 命令添加服务：

claude mcp add --transport http movk-mapbox https://mapbox.mhaibaraai.cn/mcp

Claude Desktop

1. 打开 Claude Desktop，进入「Settings」>「Developer」
2. 点击「Edit Config」打开本地配置目录
3. 修改 claude_desktop_config.json：

{
  "mcpServers": {
    "movk-mapbox": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mapbox.mhaibaraai.cn/mcp"
      ]
    }
  }
}

4. 重启 Claude Desktop

Cursor

在项目根目录创建或更新 .cursor/mcp.json：

{
  "mcpServers": {
    "movk-mapbox": {
      "type": "http",
      "url": "https://mapbox.mhaibaraai.cn/mcp"
    }
  }
}

VS Code

在项目 .vscode 目录创建或编辑 mcp.json：

{
  "servers": {
    "movk-mapbox": {
      "type": "http",
      "url": "https://mapbox.mhaibaraai.cn/mcp"
    }
  }
}

Windsurf

1. 打开 Windsurf，进入「Settings」>「Windsurf Settings」>「Cascade」
2. 点击「Manage MCPs」>「View raw config」
3. 添加配置：

{
  "mcpServers": {
    "movk-mapbox": {
      "type": "http",
      "url": "https://mapbox.mhaibaraai.cn/mcp"
    }
  }
}

ChatGPT

1. 启用开发者模式：「Settings」>「Connectors」>「Advanced settings」>「Developer mode」
2. 打开 ChatGPT 设置
3. 在 Connectors 选项卡创建新连接器：名称 Movk Mapbox、MCP server URL https://mapbox.mhaibaraai.cn/mcp、认证 None
4. 点击创建

OpenCode

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "movk-mapbox": {
      "type": "remote",
      "url": "https://mapbox.mhaibaraai.cn/mcp",
      "enabled": true
    }
  }
}

使用示例

接入后可直接向 AI 助手提问，它会自动调用上述工具：

• 「按分类列出所有图层组件」
• 「获取 MapboxLayer 的 Props」
• 「把这组 WGS84 坐标转成 GCJ02」
• 「circle 图层有哪些常用 paint 属性」
• 「找出与绘制相关的能力」
• 「按 build-mapbox-map 帮我搭一张叠天地图矢量底图、带导航控件的地图」