crm-mcp 0.3.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，留空自动探测
CRM_TRANSPORT=stdio     # 传输模式：stdio（单用户）| streamable-http（共享服务多用户）
CRM_HOST=127.0.0.1      # streamable-http 监听地址
CRM_PORT=8000           # streamable-http 监听端口
CRM_USER_STORE=         # 凭据库 JSON 路径（共享部署多用户：员工标识→CRM账密/租户）

用 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

共享服务多用户部署（方式 B）

一套服务器服务全公司员工时，crm-mcp 按身份为每个员工缓存独立的 CRM 会话 （LRU + TTL），令牌互不串扰，数据范围与写操作审计自动归属到真实操作人。

身份解析优先级：HTTP 请求头 → 员工标识 crm_user → 工具参数 crm_token → 服务端环境变量。

推荐：服务端凭据库 + 员工标识。 管理员维护一份凭据库文件（员工标识 → CRM 账号/密码/租户），用 CRM_USER_STORE 指向它；调用方只需把非秘密的 员工标识作为 crm_user 参数传入，crm-mcp 即以该员工身份登录、令牌自动续期。 账号密码只在服务端，不进入模型上下文。支持多租户。

// crm_users.json（chmod 600）
{
  "zhangsan@parent": { "username": "zhangsan", "password": "…", "tenant_id": "T001" },
  "lisi@subA":       { "username": "lisi",     "password": "…", "tenant_id": "T042" }
}

HTTP 请求头通道（待 Agent 框架支持按用户注入头后启用）：设 CRM_TRANSPORT=streamable-http，由调用方传 X-CRM-Token 或 X-CRM-Username+X-CRM-Password、可选 X-CRM-Tenant。建议绑定 127.0.0.1 并由上游反向代理终止 TLS。

未带任何身份信息时回退到环境变量（即 stdio 单用户配置）。

完整的 Hermes / OpenClaw 配置示例见 docs/multi-user-setup.md。

测试

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}