Metadata-Version: 2.4
Name: crm-mcp
Version: 0.1.0
Summary: CRM MCP Server: expose OTD CRM business queries to AI agents.
Author: OTD
License: Proprietary
Project-URL: Homepage, https://github.com/stevendingliujian-collab/crm-mcp
Project-URL: Repository, https://github.com/stevendingliujian-collab/crm-mcp
Project-URL: Issues, https://github.com/stevendingliujian-collab/crm-mcp/issues
Keywords: mcp,crm,otd,ai-agent,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: requests>=2.31
Requires-Dist: packaging>=23
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: responses>=0.25; extra == "dev"

# 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` 才真正创建。

## 安装

```bash
pip install -e ".[dev]"
```

## 配置

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

```bash
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` 拉起，无需预先安装：

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

## 运行

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

用 MCP Inspector 调试：

```bash
npx @modelcontextprotocol/inspector python -m crm_mcp.server
```

## 测试

```bash
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}`
