fxiaoke-mcp

纷享销客 OpenAPI v2 的 MCP 服务。已在 sandbox 租户全链路实测通过，目前提供 19 个工具：全部业务对象（含 __c 自定义对象）的增删改查、作废/恢复、变更负责人，公海、成交状态、查价、商机阶段推进等模块专属操作，以及客户 360° 视图、销售漏斗、报价比价等场景工具。

项目结构

src/
├── server.py            # 入口：注册 core + 全部业务域
├── fxk_client.py        # HTTP 客户端：token 缓存、统一请求、预设/自定义对象路由
├── core/
│   └── tools.py         # 通用工具（10 个，所有对象共享，勿加模块专属逻辑）
└── modules/             # 按纷享文档业务域划分（与 developer.fxiaoke.com 层级一致）
    ├── __init__.py      # 业务域注册表（DOMAINS）
    ├── base.py          # 自定义功能接口桥（APL 控制器函数 /cgi/crm/v2/special/function）
    ├── customers_and_contacts/    # 客户与联系人：account.py(客户)、account_addr.py(客户地址)
    ├── opportunities_and_leads/   # 商机与线索：opportunity.py(商机2.0)、leads.py(线索)
    ├── commodities_and_products/  # 商品与产品：product.py(产品)
    ├── quotations_and_pricing/    # 报价与价目：quote.py(报价单)、price_book.py(价目表)
    ├── contract_management/       # 合同管理：contract.py(合同对象)
    └── finance_and_payment/       # 财务与回款：account_fin.py(客户财务信息)

每个业务域包内，模块文件分两段：register_native（原生 OpenAPI 专属工具）、register_custom（平台自定义功能接口，经 base.call_custom_function 桥接）。新工具归属：对象通用能力 → core/tools.py；模块专属 → 对应业务域下模块文件。新增模块：在域包内建文件并登记到该域 MODULES；新增业务域：建域包并登记到 modules/__init__.py 的 DOMAINS。

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

工具清单

路由规则：__c 后缀的自定义对象自动走 /cgi/crm/custom/v2/data/*，预设对象走 /cgi/crm/v2/data/*。

环境准备

1. Python 3.11+，安装依赖：

   python -m venv .venv
   .\.venv\Scripts\pip.exe install -e .

2. 复制 .env.example 为 .env 并填写：

   变量	说明
   FXK_APP_ID / FXK_APP_SECRET / FXK_PERMANENT_CODE	纷享后台自建应用凭证（管理后台 → 应用列表 → 开启开发模式）
   FXK_OPEN_USER_ID	默认调用身份的 OpenUserID（FSUID_ 开头），用 get_user_id.py 通过手机号查询（见下）。仅 stdio 模式需要；HTTP 多用户模式身份逐请求由 X-Fxk-Token 解析，应留空
   FXK_API_BASE_URL	默认 https://open.fxiaoke.com，多云租户按所在云修改

3. 确认本机出口 IP 已在纷享后台白名单内（能拿到 token 即说明白名单 OK）。

本地调试

方式一：测试脚本（最快，不依赖任何客户端）

前三个脚本在进程内直接调工具、不走 HTTP，因此需要显式指定调用身份 （服务端 .env 已不再提供共享默认身份）：

$env:FXK_OPEN_USER_ID='FSUID_xxx'
.\.venv\Scripts\python.exe tests\test_e2e.py      # 4 个只读工具冒烟
.\.venv\Scripts\python.exe tests\test_p1.py       # 销售订单全生命周期闭环（写操作）
.\.venv\Scripts\python.exe tests\test_identity.py # 双身份权限对比（改 FXK_OPEN_USER_ID 切身份）

test_http.py 走 HTTP，需先启动服务并携带令牌（监听地址/端口自动读 .env）：

$env:FXK_TEST_TOKEN='fxk-xxx'
.\.venv\Scripts\python.exe tests\test_http.py     # HTTP 模式协议验证

方式二：MCP Inspector（可视化调单个工具）

npx @modelcontextprotocol/inspector .\.venv\Scripts\python.exe -m src.server

浏览器打开 Inspector 地址 → 左侧选工具 → 填参数 → 直接看返回。

方式三：HTTP 集中部署（多用户推荐）

$env:FXK_MCP_TRANSPORT='http'
.\.venv\Scripts\python.exe -m src.server     # 监听 http://127.0.0.1:8765/mcp

可选环境变量：FXK_MCP_HOST（默认 127.0.0.1）、FXK_MCP_PORT（默认 8765）。

Linux 下可用项目级管理脚本（非 systemd，日志和 pid 文件在 logs/）：

scripts/fxk-mcp.sh start     # 后台启动
scripts/fxk-mcp.sh stop      # 停止
scripts/fxk-mcp.sh restart   # 重启（改配置/identity_map.json 后立即生效）
scripts/fxk-mcp.sh status    # 运行状态 + 最近身份校验结果
scripts/fxk-mcp.sh logs      # 实时日志

身份头映射：项目根目录 identity_map.json（已 gitignore，参考 identity_map.example.json） 配置后所有 HTTP 请求必须携带 X-Fxk-Token，服务端按令牌映射到对应员工的 FSUID， 未知/缺失令牌返回 401，每次调用写 [fxk-audit] 审计日志（谁、调了什么）。 未配置映射表时退化为共用 .env 默认身份（启动会打警告）；若 .env 里也没有 FXK_OPEN_USER_ID，启动时会因身份校验失败而拒绝启动。

身份校验：映射表里的 FSUID 会在服务启动时逐个调 /cgi/user/get 校验是否为租户内 已注册且在职业用户，不合格的令牌直接置为停用（后续请求 403）；若启动时没有任何可用令牌 则拒绝启动（fail-closed）。之后由后台线程按 FXK_IDENTITY_CHECK_INTERVAL（默认 86400 秒＝一天） 定时复核，不随每次请求校验。每轮校验会重新加载 identity_map.json：新增/吊销令牌 在下一轮校验（最长一天）生效，重启服务可立即生效。

{
  "tokens": {
    "fxk-随机字符串": {"fsuid": "FSUID_员工", "name": "姓名"}
  }
}

用户侧 WorkBuddy 配置（每人一个令牌，由管理员分发）：

{
  "mcpServers": {
    "fxiaoke": {
      "type": "streamable-http",
      "url": "http://服务器IP:8765/mcp",
      "headers": {"X-Fxk-Token": "fxk-发给我的令牌"}
    }
  }
}

局域网访问需设 FXK_MCP_HOST=0.0.0.0；令牌即凭证，按密钥管理（泄露=冒用身份）。

本机若配了 HTTP 代理，访问 127.0.0.1 可能被代理拦截返回 502，调试时绕开代理（httpx 用 trust_env=False）。

客户端接入

WorkBuddy / Claude Desktop / Cherry Studio（stdio，推荐）

{
  "mcpServers": {
    "fxiaoke": {
      "command": "d:/0615/gvs_wsx/mcp开发/纷享销客/.venv/Scripts/python.exe",
      "args": ["-m", "src.server"]
    }
  }
}

HTTP 模式（需先按上面方式三启动服务）

{
  "mcpServers": {
    "fxiaoke": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

.env 从脚本所在目录加载，配置里不需要 cwd，也不含任何密钥。

接口台账（扩展开发用）

.\.venv\Scripts\python.exe scripts\crawl_docs.py      # 重新全量爬取文档（约 3 分钟）
.\.venv\Scripts\python.exe scripts\merge_catalog.py   # 刷新台账和覆盖率（改代码后跑）
.\.venv\Scripts\python.exe scripts\list_objects.py    # 拉取租户内全部业务对象
.\.venv\Scripts\python.exe scripts\list_roles.py      # 拉取租户全部角色
.\.venv\Scripts\python.exe scripts\get_user_id.py 13800138000              # 手机号查 FSUID + 角色权限
.\.venv\Scripts\python.exe scripts\get_user_id.py 13800138000 --set-env    # 查到并直接写入 .env
.\.venv\Scripts\python.exe scripts\add_user.py 13800138000                 # 查 FSUID + 生成令牌 + 写入 identity_map.json（--regen 换发）
.\.venv\Scripts\python.exe scripts\revoke_user.py fxk-xxx                  # 吊销令牌（也支持 FSUID/手机号，--list 查看当前映射）
.\.venv\Scripts\python.exe scripts\set_user_role.py 13800138000 add <roleCode>  # 分配角色（userIds 格式未打通，暂不可用）

服务日志写入 logs/ 目录（已 gitignore）。

实测踩坑备忘

• token 接口是 /cgi/corpAccessToken/get/V2（网上常见的 /cgi/accessToken、/cgi/getAccessToken 都是旧路径，404）

• 查询传参用旧式 filters[{field_name, field_values, operator}] + dataObjectApiName；新式 conditions 不生效

• describe 的参数是 apiName，不是 objectApiName

• 创建/修改默认触发审批流，记录会被锁定（无法 update/invalid/delete）；测试时传 trigger_approval_flow=False

• owner / changeOwner 的人员值是 FSUID 列表（["FSUID_xxx"]），不是员工工号

• 部分对象 name 是自动编号字段，传值会被忽略

• 主从结构对象（如销售订单）创建时必须带从对象明细（details）

• 商机阶段推进是两段式：getInstanceInfoByObjectId（参数 {entityId, objectId}）拿实例 ID → stageMoveTo 传 {workflowInstanceId, stageId}；文档里的 moveNextSaleActionStage 路由在租户上不存在，backReason__o 标注也是错的

• data/remove（公海移除）仅 AccountObj 可用，LeadsObj 路由不存在（文档与实测不符）

• 公海退回/领取依赖租户公海配置，无配置时报错文案可直接读（"公海或销售线索不存在"）

• 本租户报价单明细用的是定制对象 quote_product__c（字段带 __c 后缀），标准 QuoteLinesObj 为空；查价/比价工具已做标准→定制自动回退，且 __c 对象查询必须走 /cgi/crm/custom/v2/data/query 路由

• getRealPrice 不传 accountId 会报参数错误；价格字段是 selling_price（不是任何含 price 的字段，文档未说明）

安全

身份机制（防注入失败越权）

身份解析优先级：进程环境变量 > ~/.fxiaoke-mcp/.env > 项目 .env。

• 服务启动时强制校验身份（调用 /cgi/user/get），身份非法立即拒绝启动（fail-closed）， 并在日志打印 生效身份: 姓名 (FSUID) 来源=process_env/user_home/project_env

• 身份来自项目 .env 默认值时会打印警告——多人分发时必须删掉共享 .env 里的 FXK_OPEN_USER_ID，这样 mcp.json env 注入失败的结果是"启动失败"（可见）， 而不是"静默用管理员身份"（越权）

• 任何人可随时在对话中问"我当前是什么身份"（fxk_whoami 工具）核对

分发方式（防任务过程中代码被改）

其他

• 凭证只放 .env（已 gitignore），不要提交到 git、不要截图外传

• fxk_delete_records 等高危工具：Agent 调用前应先向用户确认