# Zoho Projects MCP

开源的 Zoho Projects 本地 MCP，同时提供 Codex 插件和 DeepSeek Harness（DSH）插件。支持筛选任务与问题、创建工单、分配人员、更新详情和进度、评论、附件及受控状态流转。

**普通用户请直接阅读：[macOS / Windows / Linux 安装与授权说明书](docs/USER-GUIDE.zh-CN.md)。** 说明书包含 Self Client 创建、权限复制、授权码填写、初始化、检查和常见问题，无需修改源码。

所有写入都必须先生成预览，再由用户明确确认。项目不包含任何公司门户 ID、个人 ZPUID、OAuth 凭据或内部项目状态 ID。

## 功能

- 按项目、负责人、标题、状态和截止日期筛选任务或问题。
- 按工单前缀查找任务，读取详情、评论和附件元数据。
- 创建任务、子任务或问题，分配负责人，更新支持的字段。
- 一次回填字段、评论、本地附件和状态，并保留执行回执。
- 重复确认返回原回执；不确定的写入不会自动重试。
- 不提供删除、关闭、批量修改或任意 Zoho API 请求工具。

DSH 中的工具名为 `mcp__zoho-projects__<工具名>`；Codex 使用同一个 MCP 服务。

## 环境要求

- macOS、Windows 或带 Secret Service 的 Linux 桌面。
- [uv](https://docs.astral.sh/uv/)，用于准备 Python 3.12 和依赖。
- Zoho Projects 账号及目标项目权限。
- Codex CLI，或包含 `@deepseek-ai/dsh-mcp-client` 的 DSH profile。

OAuth 凭据保存到当前操作系统用户的凭据存储：macOS 钥匙串、Windows 凭据管理器，或 Linux 的 GNOME Keyring、KWallet 等 Secret Service。无桌面 Secret Service 的 Linux 环境需要额外配置。

## 快速开始

### 1. 安装命令

从公开 Git 仓库安装，无需手工克隆：

```bash
uv tool install git+https://github.com/amosbake/zoho-projects-mcp.git
```

开发本地检出时使用：

```bash
uv tool install .
```

### 2. 在 Zoho 获取授权信息

在 Zoho API Console 中创建 Self Client，然后按说明书生成包含任务、问题、成员和可选附件权限的一次性授权码。完整步骤和权限文本见[普通用户说明书](docs/USER-GUIDE.zh-CN.md)。

### 3. 初始化

macOS / Linux 示例：

```bash
zoho-projects setup \
  --portal-id '你的数字门户ID' \
  --user-id '你的数字ZPUID' \
  --region cn \
  --attachment-root "$HOME/Documents"
```

Windows PowerShell 示例：

```powershell
zoho-projects setup `
  --portal-id '你的数字门户ID' `
  --user-id '你的数字ZPUID' `
  --region cn `
  --attachment-root "$HOME\Documents"
```

国际区使用 `--region global`。命令依次要求输入 Client ID、Client Secret 和一次性授权码，自动换取 Refresh Token 并保存到系统凭据存储。敏感输入不会显示在屏幕上。

已有完整 OAuth JSON 的高级用户可使用 `--oauth-json`；凭据已由其他安全配置流程写入系统凭据存储时，使用 `--skip-oauth`，并用 `--keychain-account`、`--keychain-service` 指定条目。

检查非敏感配置并执行真实只读连接：

```bash
zoho-projects config
zoho-projects doctor --online
```

配置文件默认位置：

| 系统 | 位置 |
|---|---|
| macOS | `~/Library/Application Support/zoho-projects-mcp/config.json` |
| Windows | `%APPDATA%\zoho-projects-mcp\config.json` |
| Linux | `~/.config/zoho-projects-mcp/config.json` |

Access Token 缓存、写入状态和回执也保存在用户目录，不写入插件源码。不要把 OAuth 信息、Token 缓存或用户配置提交到 Git。

## 安装 Codex 插件

```bash
codex plugin marketplace add amosbake/zoho-projects-mcp
codex plugin add zoho-projects@zoho-projects-community
```

插件通过跨平台的 `uv run` 启动本地 MCP，个人配置从统一用户目录读取。首次启动可能需要下载依赖。

也可以直接把 `zoho-projects-mcp` 注册到其他支持 stdio 的客户端。插件方式和直接注册方式不要同时启用同名服务。

## 安装 DSH 插件

```bash
dsh plugin --profile web add github:amosbake/zoho-projects-mcp
dsh --profile web --dump-config
```

`package.json` 声明 DSH bundle，`cordis.patch.yml` 使用官方 `@deepseek-ai/dsh-mcp-client`。默认从用户目录下的 `.local/bin` 启动命令；位置不同时，在 profile 自己的 patch 中覆盖 `zoho-projects-mcp` 行的 `command`。

## 使用示例

- “查询我负责的未完成任务，按截止日期排序。”
- “查找 TASK-123，读取完整详情和最近评论。”
- “在指定任务下创建子任务，先给我预览。”
- “把这份本地文档上传到指定任务，并补充进度评论。”

写入流程：

1. Agent 调用 `zoho_preview_*`。
2. Agent 展示目标、字段变化和附件。
3. 用户对该预览明确同意。
4. Agent 调用 `zoho_confirm_write` 并返回回执。

写入超时、5xx 或结果无法核对时，应先只读核对，不要自动重试。

## 状态流转配置

状态名称和数字 ID 因 Zoho 门户及项目而异。仓库只提供 `examples/` 示例，不包含真实项目映射。未配置白名单时，不允许状态流转。

可在 setup 中导入管理员提供的文件：

```bash
zoho-projects setup --skip-oauth \
  --status-map /path/to/status-map.json \
  --status-whitelist /path/to/status-whitelist.json
```

状态映射格式为 `projects -> 项目ID -> tasks/issues -> 状态名称 -> 数字状态ID`。白名单格式为 `tasks/issues -> 当前状态 -> 可流转目标列表`。

## 附件安全

只有 `--attachment-root` 明确允许的目录可以用于上传；默认没有允许目录。多个目录可重复传入该参数。附件必须是普通文件、不能是符号链接，单文件上限为 20 MB。

## CLI

```bash
zoho-projects find '{"prefix":"TASK-123"}'
zoho-projects search '{"kind":"both","owner_id":"YOUR_ZPUID","limit":10}'
zoho-projects preview-create-task '{"project_id":"...","name":"测试子任务"}'
zoho-projects confirm '{"confirmationId":"..."}'
```

## 开发与发布

```bash
uv venv --python 3.12
uv pip install --python .venv/bin/python -e .
uv build
npm pack --dry-run
```

发布时同步更新 `.codex-plugin/plugin.json`、`pyproject.toml`、`src/zoho_projects_mcp/__init__.py` 和 `package.json` 的版本。Python 包可发布到 PyPI，DSH bundle 可发布到 npm 或直接从 GitHub 安装，Codex 插件通过 Git 仓库中的 Marketplace 清单安装。

本项目是社区实现，不隶属于 Zoho、OpenAI 或 DeepSeek。使用 Zoho API 时仍需遵守对应服务条款和用户权限。

## License

[MIT](LICENSE)