NewCrm MCP 服务器基础

本项目是为现有 NewCrm CRM 单独构建的 MCP 服务器。它不修改 CRM 代码库，也不直接连接 MongoDB。

当前范围特意限定为未来 MCP 集成的干净基础。

架构

ChatGPT 工作端 ↓ OAuth 2.1 ↓ NewCrm MCP 服务器 ↓ 现有 NewCrm 后端 API ↓ MongoDB

MCP 服务器设计为尽可能通过现有后端 API 层与现有 CRM 通信。

Related MCP server: @kemosoft/mcp-heymax-crm

当前状态

项目特意不包括：

• OAuth 实现

• MCP 工具

• HubSpot 集成

• 写操作

• 新增、更新或删除操作

• MongoDB 访问

• 批量导出

• Webhooks

• 批量更新

项目结构

NewCrm-MCP/
├── src/
│   ├── audit/
│   │   └── logger.js
│   ├── auth/
│   │   └── tokenValidator.js
│   ├── config/
│   │   └── env.js
│   ├── permissions/
│   │   └── roleDefinitions.js
│   ├── services/
│   │   └── crmApiClient.js
│   ├── tools/
│   │   └── index.js
│   └── server.js
├── .env.example
├── .gitignore
├── package.json
├── README.md
└── node_modules/

安装

1. 在项目文件夹中打开终端。

2. 安装依赖：

npm install

环境变量

复制示例文件并在本地 .env 文件中设置值：

copy .env.example .env

.env 文件应包含如下值：

• PORT

• HOST

• NODE_ENV

• CRM_API_BASE_URL=https://www.jtcrm.in/api

• MCP_SERVER_NAME

• MCP_SERVER_VERSION

• LOG_LEVEL

• CRM_API_TIMEOUT_MS

不要将密钥或真实令牌提交到源代码管理中。不要在项目中存储永久管理员 JWT 或任何生产凭据。

CRM API 集成

本项目包含一个可复用的 CRM API 客户端，用于对现有 NewCrm 后端 API 进行安全的只读访问。

当前支持的端点：

• GET /api/leads

该服务特意仅限访问显式配置的端点。它不接受来自 MCP 用户的任意 URL。

示例用法：

import { getLeads } from "./src/services/crmApiClient.js";

const result = await getLeads({
  authToken: process.env.CRM_API_TEST_AUTH_TOKEN,
});

这使集成可在未来 CRM API 调用中复用，同时避免直接访问 MongoDB 和执行写操作。

安全测试指南

对于开发或测试，请在运行时由调用方或本地临时环境值传入用户级 JWT。不要将共享管理员令牌放入 .env。

本地测试流程示例：

$env:CRM_API_TEST_AUTH_TOKEN="<user_jwt_here>"
node --input-type=module -e "import { getLeads } from './src/services/crmApiClient.js'; const result = await getLeads({ authToken: process.env.CRM_API_TEST_AUTH_TOKEN }); console.log(result);"

该服务永不会记录令牌本身，且仅在调用方提供 x-auth-token 标头时才发送该标头。

运行服务器

npm start

可选的开发模式：

npm run dev

/mcp 的工作方式

本项目使用官方 MCP SDK 及 Streamable HTTP 传输。

服务器在 /mcp 上暴露单个 MCP 端点。

• POST /mcp 处理 MCP JSON-RPC 初始化和后续请求。

• 收到初始化请求时创建新会话。

• 每个会话存储其关联的 Streamable HTTP 传输。

• DELETE /mcp 在会话不再需要时将其关闭。

• GET /mcp 当前返回 405 Method Not Allowed，因为此基础尚不支持流式 GET 请求。

这是未来工具和后端集成的正确基础，无需过早添加 CRM 功能。

测试服务器

启动服务器后，确认其成功监听：

curl -i http://127.0.0.1:3002/mcp

预期行为：

• 服务器应对 /mcp 上的 GET 请求返回 HTTP 405。

• 服务器还应接受 POST 请求以进行 MCP 初始化和 JSON-RPC 通信，一旦兼容客户端连接。

成功启动由类似如下的日志指示：

{"timestamp":"...","level":"info","message":"NewCrm MCP foundation server started","host":"127.0.0.1","port":3002,"endpoint":"/mcp"}

说明

本仓库有意与现有 NewCrm 项目隔离。它是一个独立的 MCP 基础服务器，不包含直接数据库访问或 CRM 特有业务逻辑。