crm-mcp 0.1.0

CRM MCP Server: expose OTD CRM business queries to AI agents.

CRM MCP Server

把 OTD CRM 系统的业务查询能力封装成 MCP 工具，供 AI Agent（经飞书/Hermes）调用。 架构范式对齐姊妹项目 ERP-MCP：适配器模式、.env 配置、统一 Markdown 渲染、 统一错误码、+8 时区、溯源字段。

功能

提供 11 个工具 —— 8 个只读查询 + 1 个写操作 + 2 个版本管理：

工具	类型	说明
crm_query_customers	只读	按关键词 / 建档日期查客户档案
crm_query_opportunities	只读	按关键词 / 客户 / 负责人 / 金额 / 阶段查销售商机
crm_query_contracts	只读	按关键词 / 客户 / 负责人 / 是否签约查合同
crm_query_follow_ups	只读	查某关联对象（商机/客户/合同等）的跟进记录
crm_query_contacts	只读	按关键词 / 客户查联系人
crm_query_receivables	只读	按客户 / 合同 / 计划收款日期查应收款（催收用）
crm_query_invoices	只读	按客户 / 合同 / 开票状态查开票情况
crm_query_projects	只读	按关键词 / 客户 / 负责人 / 维保到期查项目
crm_create_follow_up	写	创建跟进记录（两步确认：先预览，再传 confirm=true 写入）
crm_check_update	只读	对比当前版本与 PyPI 最新版本，提示是否有新版
crm_self_update	写	升级 crm-mcp 自身（两步确认：先预览，再传 confirm=true 执行）

说明：

• 查询结果统一渲染为 Markdown 表格，含「内部ID」列 —— 该 ID 可作为 crm_query_follow_ups 的 related_id 参数，实现「查商机/客户 → 查其跟进」串联。
• CRM 只有应收，不含应付；应付请用 ERP 系统查询。
• crm_create_follow_up 为写操作，首次调用仅返回预览、不写入，须再次调用 并传 confirm=true 才真正创建。

安装

pip install -e ".[dev]"

配置

复制 .env.example 为 .env 并填写 OTD CRM 凭据：

CRM_API_URL=https://app.otd-odincloud.com
CRM_TENANT_ID=        # 填了就跳过租户发现
CRM_USERNAME=your_username
CRM_PASSWORD=your_password
CRM_USER_ID=
CRM_TIMEOUT=30
CRM_VERSION_PIN=        # 填了即锁定版本：crm_check_update 只提示、crm_self_update 拒绝升级
CRM_UPDATE_INSTALLER=   # 升级方式覆盖：uv / pip，留空自动探测

用 uvx 免安装调用

发布到 PyPI 后，MCP 客户端可直接用 uvx 拉起，无需预先安装：

{
  "mcpServers": {
    "crm": {
      "command": "uvx",
      "args": ["crm-mcp"],
      "env": {
        "CRM_USERNAME": "...",
        "CRM_PASSWORD": "...",
        "CRM_TENANT_ID": "..."
      }
    }
  }
}

运行

python -m crm_mcp.server          # stdio 模式
crm-mcp                           # 同上（安装后）

用 MCP Inspector 调试：

npx @modelcontextprotocol/inspector python -m crm_mcp.server

测试

pytest -q

升级

crm-mcp --version 查看当前版本。运行中可让 Agent 自助升级：

1. crm_check_update —— 对比当前版本与 PyPI 最新版本，返回是否有新版。
2. crm_self_update —— 两步确认的写操作：首次调用只返回升级命令预览， 传 confirm=true 才真正执行（自动探测 uv tool / pip 安装方式， target_version 可指定版本以回滚）。
3. 升级后当前进程仍运行旧版，需重启 MCP 客户端使新版生效。

设置 CRM_VERSION_PIN 可锁定版本：crm_check_update 只提示，crm_self_update 拒绝升级。

后端说明

CRM 后端是 ABP 框架（ASP.NET Boilerplate）应用：

• 多租户，请求带 __tenant 头
• 两步认证：租户发现（可选）+ 登录拿 JWT
• 响应 Content-Type 常为 text/plain，body 可能是双重编码的 JSON 字符串
• 列表查询统一 POST {pageIndex, pageSize, filter}，响应 {totalCount, items}