geoc-map-print-api MCP

这是 geoc_map_print_nest 项目的 MCP 服务，基于根目录 apifox-openapi.json 生成工具，让 Agent 可以通过 MCP tools 调用当前项目后端接口。

工具

当前版本暴露 79 个工具，对应当前 OpenAPI 文档中的 79 个接口。

工具按接口 operationId 命名，例如：

• element_manage_list_get：GET /element_manage/list
• element_manage_upload_file_post：POST /element_manage/upload_file
• map_project_project_ls_get：GET /map_project/project_ls
• map_carto_start_post：POST /map_carto/start
• project_set_create_post：POST /project_set/create
• project_set_project_batch_create_noauth_post：POST /project_set/project/batch_create/noauth
• project_set_mvt_z_x_y_mvt_get：GET /project_set/mvt/{z}/{x}/{y}.mvt

生成工具会按 OpenAPI schema 区分 path、query、header 和 body 参数，并支持 JSON、application/x-www-form-urlencoded、multipart/form-data 三类请求体。二进制响应会以 JSON 结构返回：

{
  "type": "binary",
  "contentType": "application/x-protobuf",
  "byteLength": 123,
  "base64": "..."
}

删除、清理、创建、更新等写入型接口会通过 MCP tool annotations 标注 destructiveHint 或非只读。Agent 调用这些工具前应确认参数和影响范围，不要配置自动批准。

环境变量

• GEOC_MAP_PRINT_BASE_URL：接口基础地址，默认 http://localhost:7101/gmp/api/v1
• GEOC_MAP_PRINT_AUTH_TOKEN：接口鉴权 token，可直接写 token，服务会自动补 Bearer
• GEOC_MAP_PRINT_TOKEN：GEOC_MAP_PRINT_AUTH_TOKEN 的兼容别名
• GEOC_MAP_PRINT_AUTHORIZATION：完整 Authorization 值；设置后优先使用
• GEOC_MAP_PRINT_TIMEOUT_MS：请求超时时间，默认 120000

不要把真实 token 写入代码、README、提交或共享配置。真实 token 应通过个人本地环境变量、Keychain、1Password、CI secret 或 MCP 客户端的私有配置管理。

本地运行

npm install
npm run generate:tools
npm test
npm run build
GEOC_MAP_PRINT_BASE_URL=http://localhost:7101/gmp/api/v1 npm start

接口发生变化后，在仓库根目录先更新 apifox-openapi.json：

node scripts/generate-apifox-openapi.cjs

再回到 MCP 包重新生成工具：

cd mcp/geoc-map-print-api
npm run generate:tools
npm test
npm run build

更多 AI Agent / IDE / MCP 客户端接入方式见 AGENT_SETUP.md。

发布为 npm 包

发布前确认 package.json 中的版本号是新版本，并确认你已经登录可发布当前 scope 的 npm registry。

cd mcp/geoc-map-print-api
npm whoami
npm test
npm run build
npm pack --dry-run
npm publish --access public

当前包名是 @yinyoudexing/geoc-map-print-api-mcp。如果公司使用内网 registry，不要把 registry 写死到包里，优先在本机或 CI 的 .npmrc 中配置。

Codex MCP 配置

包发布后，Codex 配置应使用 npx 启动，不依赖本机绝对路径：

[mcp_servers.geoc-map-print-api]
command = "npx"
args = ["-y", "@yinyoudexing/[email protected]"]

[mcp_servers.geoc-map-print-api.env]
GEOC_MAP_PRINT_BASE_URL = "http://localhost:7101/gmp/api/v1"
GEOC_MAP_PRINT_AUTH_TOKEN = "your-token"

升级版本时，先发布新版本，再把 MCP 配置中的版本号改到新版本。