SuperAPI AI 工具集

mcp-server

编程与开发

查看项目

更新于 10-16 06:58

技能介绍

用途

本技能用于指导用户创建新的 MCP(Model Context Protocol)服务器集成。当需要为 Cursor 新增一个 MCP 服务时,可参照本指南完成目录搭建、工具描述编写、服务器配置与调用测试。

目录结构

MCP 存放位置为:~/.cursor/projects/<project>/mcps/<server-name>/

其结构示例如下:

mcps/
├── user-notion/
│   └── tools/
│       ├── API-retrieve-a-page.json
│       └── ...
├── cursor-ide-browser/
│   └── tools/
│       ├── browser_navigate.json
│       └── ...
└── user-n8n-mcp/
    └── tools/
        └── ...

工具描述格式

每个工具为一个 JSON 文件,格式如下:

{
  "name": "tool-name",
  "description": "What this tool does",
  "arguments": {
    "type": "object",
    "properties": {
      "param1": { "type": "string", "description": "..." }
    },
    "required": ["param1"]
  }
}

使用方式

调用时遵循以下模式:

  • 调用前先读取工具描述
  • 使用 CallMcpTool 传入 server、toolName、arguments
  • 妥善处理返回结果

调用示例:

CallMcpTool:
  server: "user-notion"
  toolName: "API-retrieve-a-page"
  arguments: { "page_id": "abc123" }

现有 MCP 参考

资料中列出的现有 MCP 及其能力:

MCP 能力
user-notion 页面/块 CRUD、搜索、评论
cursor-ide-browser 导航、点击、截图、控制台
user-n8n-mcp 工作流搜索、详情、执行
user-context7 库文档查询
figma 设计规格、从画框生成代码

创建新 MCP 的步骤

  1. 创建目录:mcps/<server-name>/tools/
  2. 添加工具描述 JSON 文件
  3. 在 ~/.cursor/mcp.json 中配置服务器
  4. 重启 Cursor(Cmd+Shift+P > "Reload Window")
  5. 使用 CallMcpTool 测试

认证模式

资料列出三种认证模式:

模式一:API Token(env 块)

适用于使用 API 密钥的 MCP(如 Notion、n8n):

"mcp-name": {
  "command": "npx",
  "args": ["-y", "@package/mcp-server"],
  "env": {
    "API_KEY": "your-token-here"
  }
}

模式二:基于 URL(无认证)

适用于连接本地服务器的 MCP(如 Figma 桌面版):

"mcp-name": {
  "url": "http://127.0.0.1:PORT/mcp"
}

模式三:OAuth(远程 URL)

适用于使用浏览器 OAuth 的 MCP(如 Figma 远程):

"mcp-name": {
  "url": "https://service.com/mcp"
}

添加后,需在 Cursor MCP 设置中点击 "Connect" 进行授权。

问题排查

  • 安装无限循环:取消并手动编辑 ~/.cursor/mcp.json,直接添加配置块,然后重启 Cursor。
  • MCP 未显示:检查 JSON 语法是否有效,确认包名正确,修改后重启 Cursor。

最佳实践

  • 调用前始终读取工具 schema
  • 优雅地处理错误
  • 使用描述性的工具名称
  • 明确区分必填与可选参数

限制

资料未提供具体支持的平台范围、版本要求、收费信息或性能指标。