isp-coze-mcp-server

v1.0.9

Published

9 months ago

扣子API MCP服务器 - 提供与扣子平台交互的MCP工具

0High
0Medium
0Low

janmeeluo

mcp coze api server openapi chat cursor ai isp

扣子API MCP服务器

一个用于Cursor编辑器的MCP服务器，提供与扣子(Coze)平台的API交互功能。支持获取OpenAPI文档和聊天对话功能。

功能特性

🤖 与扣子聊天机器人交互
📋 获取标准OpenAPI文档
📝 详细的日志记录
🐛 完整的调试工具
🚀 简单易用的安装方式
🔧 支持npx直接运行（无需安装）

快速开始

方式一：使用npx（推荐，无需安装）

直接在Cursor中配置，无需全局安装：

{
  "mcpServers": {
    "coze-api": {
      "command": "npx",
      "args": ["isp-coze-mcp-server"],
      "env": {
        "COZE_API_TOKEN": "your-coze-api-token",
        "COZE_BOT_ID": "your-bot-id",
        "COZE_BASE_URL": "https://api.coze.cn",
        "COZE_USER_ID": "cursor"
      }
    }
  }
}

方式二：全局安装

npm install -g isp-coze-mcp-server

然后在Cursor中配置：

{
  "mcpServers": {
    "coze-api": {
      "command": "isp-coze-mcp-server",
      "env": {
        "COZE_API_TOKEN": "your-coze-api-token",
        "COZE_BOT_ID": "your-bot-id",
        "COZE_BASE_URL": "https://api.coze.cn",
        "COZE_USER_ID": "cursor"
      }
    }
  }
}

环境变量配置

无论使用哪种方式，都需要配置以下环境变量：

export COZE_API_TOKEN="your-coze-api-token"
export COZE_BOT_ID="your-bot-id"
export COZE_BASE_URL="https://api.coze.cn"  # 可选
export COZE_USER_ID="cursor"                # 可选

可用命令

npx方式: npx isp-coze-mcp-server
全局安装后: isp-coze-mcp-server

支持的工具

getOpenApi

获取标准OpenAPI文档结构。

参数：

serviceName (string) - 对接服务名称
apiNameOrPath (string) - 需要获取的接口名称或路径

示例：

{
  "serviceName": "fa-auth",
  "apiNameOrPath": "login"
}

环境变量说明

| 变量名 | 必需 | 默认值 | 说明 | |--------|------|--------|------| | COZE_API_TOKEN | 是 | - | 扣子API访问令牌 | | COZE_BOT_ID | 是 | - | 扣子机器人ID | | COZE_BASE_URL | 否 | https://api.coze.cn | 扣子API基础URL | | COZE_USER_ID | 否 | cursor | 用户ID | | MCP_DEBUG | 否 | false | 启用调试模式 | | MCP_LOG_LEVEL | 否 | info | 日志级别 | | MCP_LOG_FILE | 否 | - | 日志文件路径 |

调试

启用调试模式

# 方法1：设置环境变量
export MCP_DEBUG=true
export MCP_LOG_LEVEL=debug
isp-coze-mcp-server

# 方法2：直接在Cursor配置中设置
{
  "mcpServers": {
    "coze-api": {
      "command": "isp-coze-mcp-server",
      "env": {
        "COZE_API_TOKEN": "your-token",
        "COZE_BOT_ID": "your-bot-id",
        "MCP_DEBUG": "true",
        "MCP_LOG_LEVEL": "debug",
        "MCP_LOG_FILE": "/tmp/mcp-debug.log"
      }
    }
  }
}

查看日志

如果设置了日志文件，可以实时查看：

tail -f /tmp/mcp-debug.log

故障排除

1. "npx isp-coze-mcp-server运行后没有任何响应"

这是正常现象！MCP服务器的输出被发送到stderr（错误流），在某些终端环境下可能不可见。

解决方案：

# 查看完整输出（包括stderr）
npx isp-coze-mcp-server 2>&1

# 或者重定向到文件查看
npx isp-coze-mcp-server > output.log 2>&1 &
sleep 3
cat output.log

预期输出：

[INFO] 启动MCP服务器...
[WARN] 缺少必要的环境变量: COZE_API_TOKEN, COZE_BOT_ID
[INFO] ⚠️  服务器将启动，但功能受限
[INFO] 📋 请在Cursor中设置以下环境变量:
[INFO]   COZE_API_TOKEN - 扣子API访问令牌
[INFO]   COZE_BOT_ID - 扣子机器人ID
[INFO] 扣子API MCP服务器已启动，等待连接...

2. "client closed" 错误

这是最常见的问题，通常是环境变量配置不正确导致的。

快速解决方案：

# 运行诊断工具
npx isp-coze-mcp-server
# 然后按照提示操作

详细解决步骤：查看 CURSOR_CLIENT_CLOSED_FIX.md

常见原因：

❌ 使用了示例值而非真实的API令牌
❌ 机器人ID不正确或无权限
❌ 网络连接问题
❌ npx缓存问题

3. 安装失败

确保Node.js版本 >= 18.0.0：

node -v

4. 权限问题

如果全局安装遇到权限问题：

# macOS/Linux
sudo npm install -g isp-coze-mcp-server

# 或者使用npx（无需全局安装）
npx isp-coze-mcp-server

5. 环境变量未生效

检查环境变量是否正确设置：

echo $COZE_API_TOKEN
echo $COZE_BOT_ID

6. Cursor中找不到MCP工具

确保Cursor配置正确
重启Cursor
检查命令是否在PATH中
查看调试指南

开发

本地开发

# 克隆仓库
git clone https://github.com/your-org/isp-interface-mcp.git
cd isp-interface-mcp/nodejs-mcp-server

# 安装依赖
npm install

# 启动开发服务器
npm run dev

测试

# 运行测试
npm test

# 调试模式
npm run debug

更新日志

v1.0.1

移除MaxHub专用服务器
简化配置和使用方式
修复包发布问题

v1.0.0

初始发布
支持扣子API交互
完整的日志和调试功能

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

支持

如果您遇到问题，请：

查看调试指南
提交Issue