mapbox-create-map-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1,184 +1,216 @@
-# @gis/mapbox-create-map
+# mapbox-create-map-mcp
 
-一个基于Mapbox的地理数据可视化工具（MCP），可以根据用户需求和地理数据生成一次性临时的地图可视化展示。
+一个基于Mapbox的地理数据可视化MCP工具，根据用户需求和地理数据生成图层配置信息。
 
 ## 安装
 
 ```bash
-npm install @gis/mapbox-create-map mapbox-gl
+npm install mapbox-create-map-mcp
 ```
 
-## 使用方法
+## MCP 服务使用
+
+### 直接启动
+
+```bash
+npx mapbox-create-map-mcp
+```
+
+### MCP 客户端配置
+
+在 MCP 客户端（如 Claude Desktop、Cursor 等）的配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "mapbox-createmap": {
+      "command": "npx",
+      "args": ["mapbox-create-map-mcp"]
+    }
+  }
+}
+```
+
+### MCP 工具
+
+**CreateMap** - 根据配置生成地图图层配置信息
+
+输入参数：
+- `title` (string, 必需): 地图标题
+- `description` (string, 必需): 地图描述
+- `layers` (array, 必需): 图层配置数组
+- `baseStyle` (string, 可选): 底图样式
+- `center` (array, 可选): 中心点 [经度, 纬度]
+- `zoom` (number, 可选): 缩放级别
+
+## JavaScript 库使用
 
 ### 基本使用
 
 ```javascript
-import CreateMap from '@gis/mapbox-create-map';
+import CreateMap from 'mapbox-create-map-mcp';
 
 // 初始化工具
-const createMap = new CreateMap('map-container-id', 'your-mapbox-access-token');
+const createMap = new CreateMap();
 
 // 配置地图
 const config = {
   title: "我的地图标题",
   description: "地图描述信息",
-  baseStyle: "light", // 底图样式
-  center: [116.3974, 39.9092], // 中心点
-  zoom: 10, // 缩放级别
+  baseStyle: "light",
+  center: [116.3974, 39.9092],
+  zoom: 10,
   layers: [
-    // 图层配置
+    {
+      type: "point",
+      id: "my-points",
+      fileUrl: "https://example.com/points.geojson",
+      config: {
+        'circle-color': '#FF0000',
+        'circle-radius': 8,
+        'circle-opacity': 0.8
+      }
+    }
   ]
 };
 
-// 生成地图配置信息
+// 生成图层配置信息
 createMap.create(config)
   .then(result => {
-    console.log("地图配置信息生成成功", result);
-    // result 是 GeoJSON 格式的图层配置信息，可用于自定义渲染
+    console.log("生成成功", result);
+    // result 是 FeatureCollection 格式，包含图层配置信息
   })
   .catch(error => {
-    console.error("地图配置信息生成失败", error);
+    console.error("生成失败", error);
   });
 ```
 
-### 图层类型
-
-#### 点类型要素图层
+### 返回格式
 
-##### 散点 (scatter)
 ```javascript
 {
-  type: 'scatter',
-  id: 'my-scatter-layer',
-  data: geojsonData, // 或 fileUrl: 'path/to/data.geojson'
-  color: '#3f87db',      // 填充颜色
-  size: 8,               // 点大小，默认8px
-  opacity: 100,          // 透明度，0-100
-  strokeColor: '#ffffff',// 描边颜色
-  strokeWidth: 0         // 描边宽度
+  type: "FeatureCollection",
+  features: [
+    {
+      data: "https://example.com/points.geojson",
+      properties: {
+        name: "my-points",
+        type: "point",
+        style: {
+          type: "point",
+          "circle-color": "#FF0000",
+          "circle-radius": 8,
+          "circle-opacity": 0.8
+        }
+      }
+    }
+  ]
 }
 ```
 
-##### 图标点 (icon)
-```javascript
-{
-  type: 'icon',
-  id: 'my-icon-layer',
-  data: geojsonData,
-  iconImage: 'car-15',   // 图标图片
-  iconRotate: 0,         // 图标旋转角度
-  size: 24               // 图标大小
-}
-```
+## 图层类型
 
-##### 文字点 (text)
-```javascript
-{
-  type: 'text',
-  id: 'my-text-layer',
-  data: geojsonData,
-  textColor: '#000000',   // 文字颜色
-  textSize: 12,          // 字体大小
-  textHaloColor: '#ffffff', // 文字描边颜色
-  textHaloWidth: 2       // 文字描边宽度
-}
-```
+仅支持三种几何类型：`point`、`linestring`、`polygon`
 
-##### 热力点 (heatmap)
-```javascript
-{
-  type: 'heatmap',
-  id: 'my-heatmap-layer',
-  data: geojsonData,
-  color: ['#3288bd', '#abdda4', '#fee08b', '#f46d43', '#d53e4f'], // 色带
-  radius: 20,            // 热力半径
-  weight: 1              // 热力点权重
-}
-```
+### point（点图层）
+
+对应 Mapbox circle 图层
 
-##### 3D热力点 (heatmap3d)
 ```javascript
 {
-  type: 'heatmap3d',
-  id: 'my-heatmap3d-layer',
-  data: geojsonData,
-  color: ['#000', '#555', '#fff'], // 色带
-  radius: 20,            // 热力半径
-  weight: 1              // 热力点权重
+  type: "point",
+  id: "my-points",
+  fileUrl: "path/to/data.geojson",
+  config: {
+    'circle-color': '#0000FF',           // 填充颜色
+    'circle-radius': 5,                   // 半径（像素）
+    'circle-opacity': 1,                  // 填充透明度 0-1
+    'circle-stroke-color': '#000000',    // 边框颜色
+    'circle-stroke-width': 0,            // 边框宽度（像素）
+    'circle-stroke-opacity': 1,          // 边框透明度 0-1
+    'circle-blur': 0,                    // 模糊量（像素）
+    'circle-translate': [0, 0],          // 偏移量 [x, y]
+    'circle-translate-anchor': 'map',    // 偏移参考 'map' | 'viewport'
+    'circle-pitch-scale': 'map',         // 倾斜缩放 'map' | 'viewport'
+    'circle-pitch-alignment': 'viewport' // 倾斜方向 'map' | 'viewport'
+  }
 }
 ```
 
-#### 线类型要素图层
+### linestring（线图层）
+
+对应 Mapbox line 图层
 
-##### 线 (line)
 ```javascript
 {
-  type: 'line',
-  id: 'my-line-layer',
-  data: geojsonData,
-  color: '#3f87db',      // 线颜色
-  opacity: 100,          // 透明度
-  width: 2,              // 线宽度
-  dash: 'solid'          // 实线或虚线 ('solid' 或 'dash')
+  type: "linestring",
+  id: "my-lines",
+  fileUrl: "path/to/data.geojson",
+  config: {
+    'line-color': '#FF0000',    // 线条颜色
+    'line-width': 1,            // 线条宽度
+    'line-opacity': 1,          // 透明度 0-1
+    'line-blur': 0,             // 模糊度
+    'line-gap-width': 0,        // 间隙宽度
+    'line-offset': 0,           // 偏移量
+    'line-dasharray': null      // 虚线样式，如 [2, 2]
+  }
 }
 ```
 
-#### 面类型要素图层
+### polygon（面图层）
 
-##### 填充面 (fill)
-```javascript
-{
-  type: 'fill',
-  id: 'my-fill-layer',
-  data: geojsonData,
-  color: '#3f87db',      // 填充颜色
-  opacity: 50,           // 透明度
-  strokeColor: '#ffffff',// 描边颜色
-  strokeWidth: 1         // 描边宽度
-}
-```
+对应 Mapbox fill 图层
 
-##### 三维拉伸面 (extrusion)
 ```javascript
 {
-  type: 'extrusion',
-  id: 'my-extrusion-layer',
-  data: geojsonData,
-  color: '#3f87db',      // 填充颜色
-  opacity: 80,           // 透明度
-  height: 100            // 拉伸高度（米）
+  type: "polygon",
+  id: "my-polygons",
+  fileUrl: "path/to/data.geojson",
+  config: {
+    'fill-color': '#FFFF00',         // 填充颜色
+    'fill-opacity': 1,               // 填充透明度 0-1
+    'fill-outline-color': '#000000', // 边框颜色
+    'fill-antialias': true,          // 抗锯齿
+    'fill-z-offset': 0               // 高程偏移（米）
+  }
 }
 ```
 
-### 底图样式
+## 底图样式
 
-- `whitesmoke`: 淡白色
-- `light`: 白色
-- `dark`: 黑色
-- `blue`: 靛青蓝
-- `darkblue`: 深蓝
-- `grey`: 灰色
-- `fresh`: 草绿色
+- `standard`: 标准
+- `light`: 浅色
+- `dark`: 深色
 - `satellite`: 卫星图
 
 ## API
 
-### CreateMap(container, accessToken)
+### CreateMap()
 
-构造函数，初始化CreateMap实例。
-
-- `container`: DOM容器ID或DOM元素
-- `accessToken`: Mapbox访问令牌（可选，如果不传则需提前设置）
+构造函数，初始化实例。
 
 ### create(config)
 
-创建地图。
+生成图层配置信息。
+
+**参数：**
+- `config.title` (string, 必需): 地图标题
+- `config.description` (string, 必需): 地图描述
+- `config.layers` (array, 必需): 图层配置数组
+- `config.baseStyle` (string, 可选): 底图样式，默认 'light'
+- `config.center` (array, 可选): 中心点 [经度, 纬度]
+- `config.zoom` (number, 可选): 缩放级别
+
+**返回：** Promise，resolve 后返回 FeatureCollection 格式的配置信息
+
+### metadata
 
-- `config`: 配置对象
+获取参数元数据定义，包含所有参数的类型、默认值、描述等信息。
 
-### destroy()
+### layerMetadata
 
-销毁地图实例，清理资源。
+获取各图层类型的配置属性元数据。
 
 ## 开发
 
@@ -186,19 +218,19 @@ createMap.create(config)
 # 安装依赖
 npm install
 
-# 开发模式（监听变化）
+# 开发模式
 npm run dev
 
-# 构建生产版本
+# 构建
 npm run build
 
-# 运行测试
+# 测试
 npm test
 
-# 代码检查
-npm run lint
+# 发布
+npm run publish:npm
 ```
 
 ## 许可证
 
-MIT
+MIT

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+/**
+ * mapbox-create-map-mcp CLI
+ * MCP 服务端入口
+ */
+
+const { McpServer } = require('../src/server.js');
+
+const server = new McpServer();
+server.start();

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "mapbox-create-map-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A Mapbox-based MCP tool for creating geographic data visualizations",
   "main": "dist/index.js",
   "module": "src/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "mapbox-create-map-mcp": "./bin/cli.js"
+  },
   "files": [
     "dist",
-    "src"
+    "src",
+    "bin"
   ],
   "scripts": {
     "build": "webpack --mode production",

package/src/server.js

@@ -0,0 +1,301 @@
+/**
+ * MCP Server - mapbox-create-map-mcp
+ * 实现 Model Context Protocol 服务端
+ */
+
+const readline = require('readline');
+const path = require('path');
+
+// 尝试加载打包后的版本，如果不存在则提示构建
+let CreateMap;
+try {
+  const distPath = path.join(__dirname, '../dist/index.js');
+  const module = require(distPath);
+  // UMD格式导出的是MapboxCreateMap，默认导出在.default中
+  CreateMap = module.default || module;
+} catch (e) {
+  console.error('Error: Please run "npm run build" first');
+  console.error(e.message);
+  process.exit(1);
+}
+
+class McpServer {
+  constructor() {
+    this.createMap = new CreateMap();
+    this.serverInfo = {
+      name: 'mapbox-create-map-mcp',
+      version: '1.0.0',
+      description: '基于Mapbox的地理数据可视化MCP工具'
+    };
+  }
+
+  /**
+   * 启动MCP服务
+   */
+  start() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false
+    });
+
+    rl.on('line', (line) => {
+      try {
+        const request = JSON.parse(line);
+        this.handleRequest(request);
+      } catch (error) {
+        this.sendError(-32700, 'Parse error', null);
+      }
+    });
+
+    rl.on('close', () => {
+      process.exit(0);
+    });
+
+    // 发送服务就绪信号
+    process.stderr.write('MCP Server started\n');
+  }
+
+  /**
+   * 处理MCP请求
+   */
+  async handleRequest(request) {
+    const { id, method, params } = request;
+
+    try {
+      let result;
+
+      switch (method) {
+        case 'initialize':
+          result = this.handleInitialize(params);
+          break;
+
+        case 'tools/list':
+          result = this.handleToolsList();
+          break;
+
+        case 'tools/call':
+          result = await this.handleToolsCall(params);
+          break;
+
+        case 'resources/list':
+          result = this.handleResourcesList();
+          break;
+
+        default:
+          this.sendError(-32601, `Method not found: ${method}`, id);
+          return;
+      }
+
+      this.sendResponse(id, result);
+    } catch (error) {
+      this.sendError(-32000, error.message, id);
+    }
+  }
+
+  /**
+   * 处理初始化请求
+   */
+  handleInitialize(params) {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: {
+        tools: {},
+        resources: {}
+      },
+      serverInfo: this.serverInfo
+    };
+  }
+
+  /**
+   * 处理工具列表请求
+   */
+  handleToolsList() {
+    const metadata = this.createMap.metadata;
+    const layerMetadata = this.createMap.layerMetadata;
+
+    // 合并所有图层类型的配置属性
+    const allConfigProperties = {};
+    
+    // point 属性
+    for (const key in layerMetadata.point) {
+      const prop = layerMetadata.point[key];
+      allConfigProperties[key] = {
+        type: prop.type,
+        description: `[point图层] ${prop.description}`
+      };
+      if (prop.default !== undefined) allConfigProperties[key].default = prop.default;
+    }
+    
+    // linestring 属性
+    for (const key in layerMetadata.linestring) {
+      const prop = layerMetadata.linestring[key];
+      allConfigProperties[key] = {
+        type: prop.type,
+        description: `[linestring图层] ${prop.description}`
+      };
+      if (prop.default !== undefined) allConfigProperties[key].default = prop.default;
+    }
+    
+    // polygon 属性
+    for (const key in layerMetadata.polygon) {
+      const prop = layerMetadata.polygon[key];
+      allConfigProperties[key] = {
+        type: prop.type,
+        description: `[polygon图层] ${prop.description}`
+      };
+      if (prop.default !== undefined) allConfigProperties[key].default = prop.default;
+    }
+
+    return {
+      tools: [
+        {
+          name: 'CreateMap',
+          description: '根据配置生成地图图层配置信息，返回FeatureCollection格式的结果用于渲染。图层类型支持point(点)、linestring(线)、polygon(面)三种。',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              title: {
+                type: 'string',
+                description: metadata.title.description
+              },
+              description: {
+                type: 'string',
+                description: metadata.description.description
+              },
+              baseStyle: {
+                type: 'string',
+                enum: metadata.baseStyle.enum,
+                description: metadata.baseStyle.description
+              },
+              center: {
+                type: 'array',
+                items: { type: 'number' },
+                description: metadata.center.description
+              },
+              zoom: {
+                type: 'number',
+                description: metadata.zoom.description
+              },
+              layers: {
+                type: 'array',
+                description: '图层配置数组。每个图层需要id和type，type决定了config中可用的属性：point类型用circle-*属性，lingestring类型用line-*属性，polygon类型用fill-*属性',
+                items: {
+                  type: 'object',
+                  properties: {
+                    id: { type: 'string', description: '图层唯一标识符' },
+                    type: {
+                      type: 'string',
+                      enum: ['point', 'linestring', 'polygon'],
+                      description: '图层类型: point(点,使用circle-*属性), linestring(线,使用line-*属性), polygon(面,使用fill-*属性)'
+                    },
+                    data: { type: 'object', description: 'GeoJSON格式的地理数据' },
+                    fileUrl: { type: 'string', description: '数据URL地址' },
+                    config: {
+                      type: 'object',
+                      description: '图层样式配置，根据type选择对应属性: point用circle-*、linestring用line-*、polygon用fill-*',
+                      properties: allConfigProperties
+                    }
+                  },
+                  required: ['id', 'type']
+                }
+              }
+            },
+            required: ['title', 'description', 'layers']
+          }
+        }
+      ]
+    };
+  }
+
+  /**
+   * 格式化属性元数据
+   */
+  formatProperties(meta) {
+    const props = {};
+    for (const key in meta) {
+      const prop = meta[key];
+      props[key] = {
+        type: prop.type,
+        default: prop.default,
+        description: prop.description
+      };
+      if (prop.enum) {
+        props[key].enum = prop.enum;
+      }
+      if (prop.min !== undefined) {
+        props[key].minimum = prop.min;
+      }
+      if (prop.max !== undefined) {
+        props[key].maximum = prop.max;
+      }
+    }
+    return props;
+  }
+
+  /**
+   * 处理工具调用请求
+   */
+  async handleToolsCall(params) {
+    const { name, arguments: args } = params;
+
+    if (name !== 'CreateMap') {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    try {
+      const result = await this.createMap.create(args);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: ${error.message}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+
+  /**
+   * 处理资源列表请求
+   */
+  handleResourcesList() {
+    return { resources: [] };
+  }
+
+  /**
+   * 发送响应
+   */
+  sendResponse(id, result) {
+    const response = {
+      jsonrpc: '2.0',
+      id,
+      result
+    };
+    console.log(JSON.stringify(response));
+  }
+
+  /**
+   * 发送错误
+   */
+  sendError(code, message, id) {
+    const response = {
+      jsonrpc: '2.0',
+      id,
+      error: { code, message }
+    };
+    console.log(JSON.stringify(response));
+  }
+}
+
+module.exports = { McpServer };