cunkebao_v3/Moncter/MCP/快速开始.md

Moncter MCP Server 快速开始

一、安装 MCP Server

Windows

cd MCP/moncter-mcp-server
install.bat

Linux/Mac

cd MCP/moncter-mcp-server
chmod +x install.sh
./install.sh

手动安装

cd MCP/moncter-mcp-server
npm install
npm run build

二、配置 MCP 客户端

方式1：使用相对路径（推荐）

编辑 MCP/mcp.json，使用相对于项目根目录的路径：

{
  "mcpServers": {
    "Moncter": {
      "command": "node",
      "args": ["./MCP/moncter-mcp-server/dist/index.js"],
      "cwd": "E:/Cunkebao/Cunkebao02/Moncter",
      "env": {
        "MONCTER_API_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

注意：cwd 需要修改为你的实际项目路径。

方式2：使用绝对路径

{
  "mcpServers": {
    "Moncter": {
      "command": "node",
      "args": ["E:/Cunkebao/Cunkebao02/Moncter/MCP/moncter-mcp-server/dist/index.js"],
      "env": {
        "MONCTER_API_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

方式3：使用 npx（如果发布到npm）

{
  "mcpServers": {
    "Moncter": {
      "command": "npx",
      "args": ["-y", "moncter-mcp-server"],
      "env": {
        "MONCTER_API_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

三、确保后端服务运行

确保 Moncter 后端服务正在运行：

# 检查服务状态
php start.php status

# 如果未运行，启动服务
php start.php start

默认端口：8787

四、测试 MCP Server

在 Claude Desktop 中使用

1. 打开 Claude Desktop
2. 在设置中添加 MCP 服务器配置（引用 mcp.json）
3. 重启 Claude Desktop
4. 在对话中尝试："列出所有数据源"

使用 MCP Inspector 测试

# 安装 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 测试服务器
cd MCP/moncter-mcp-server
npx @modelcontextprotocol/inspector node dist/index.js

五、使用示例

示例1：创建数据采集任务

对 AI 说：

"创建一个实时监听的数据采集任务，名称为'订单采集'，从数据源'data_source_123'的数据库'KR_商城'的集合'21年贝蒂喜订单整合'采集数据"

AI 会调用 create_data_collection_task 工具来创建任务。

示例2：创建标签任务

对 AI 说：

"创建一个全量标签计算任务，名称为'高价值用户标签'，计算所有标签，每天凌晨2点执行"

AI 会调用 create_tag_task 工具来创建任务。

示例3：查询数据源

对 AI 说：

"列出所有启用的数据源"

AI 会调用 get_data_sources 工具。

六、可用的工具列表

工具名称	功能	主要参数
create_data_collection_task	创建数据采集任务	name, data_source_id, database, collection, mode
create_tag_task	创建标签任务	name, task_type, target_tag_ids
list_data_collection_tasks	列出数据采集任务	page, page_size
list_tag_tasks	列出标签任务	page, page_size
get_data_sources	获取数据源列表	type, status
get_tag_definitions	获取标签定义列表	status
start_data_collection_task	启动数据采集任务	task_id
start_tag_task	启动标签任务	task_id

详细参数说明请查看 MCP/MCP服务器使用说明.md。

七、故障排除

问题1：找不到模块

错误：Cannot find module '@modelcontextprotocol/sdk'

解决：

cd MCP/moncter-mcp-server
npm install

问题2：编译失败

错误：TypeScript 编译错误

解决：

• 检查 Node.js 版本（需要 >= 18）
• 检查 TypeScript 版本
• 运行 npm install 重新安装依赖

问题3：无法连接到后端

错误：API请求错误: connect ECONNREFUSED

解决：

1. 检查后端服务是否运行：php start.php status
2. 检查 MONCTER_API_URL 环境变量是否正确
3. 检查端口是否被占用：netstat -ano | findstr :8787

问题4：路径错误

错误：Cannot find module 或路径相关错误

解决：

• 检查 mcp.json 中的路径是否正确
• 使用绝对路径而不是相对路径
• 确保 cwd 设置正确

八、开发调试

查看日志

MCP 服务器的错误日志会输出到 stderr，可以在 MCP 客户端中查看。

本地测试

cd MCP/moncter-mcp-server
npm run dev

然后使用 MCP Inspector 连接测试。

---

需要帮助？ 查看 MCP/MCP服务器使用说明.md 获取详细文档。