# 泛微 E10 OA MCP 服务

通过 MCP (Model Context Protocol) 连接泛微 E10 OA，查询程序修改流程列表和详情。

## 快速开始

### 1. 安装

```bash
# Windows
setup.bat

# Linux / macOS
chmod +x setup.sh && ./setup.sh
```

或手动安装：

```bash
pip install -e .
```

### 2. 配置

复制 `.env.example` 为 `.env`，填入实际配置：

```ini
WEAVER_BASE_URL=http://oa.yourcompany.com
WEAVER_CORPID=your_corpid
WEAVER_APP_KEY=your_app_key
WEAVER_APP_SECRET=your_app_secret
WEAVER_USER_ID=your_user_id          # E10 长数字格式
WEAVER_WORKFLOW_ID=your_workflow_id  # 程序修改流程的工作流ID
```

### 3. 启动

```bash
python -m weaver_mcp
```

### 4. 接入 MCP 客户端

在 MCP 客户端配置文件中添加（参考 `mcp-config.example.json`）：

```json
{
  "mcpServers": {
    "weaver-oa": {
      "command": "python",
      "args": ["-m", "weaver_mcp"],
      "cwd": "/path/to/weaver-mcp"
    }
  }
}
```

也可通过环境变量直接配置，无需 `.env` 文件。

## MCP 工具列表

| 工具名 | 功能 | 说明 |
|--------|------|------|
| `test_connection` | 测试连接 | 验证 OAuth2 认证和配置是否正确 |
| `list_program_modification_workflows` | 查询程序修改流程列表 | 支持 `date_range` 日期筛选 |
| `get_workflow_detail` | 获取流程详情 | 包含表单数据、审批记录 |
| `get_program_modification_details` | 组合查询 | 一步完成列表+详情 |
| `list_all_workflows` | 所有流程列表 | 支持 `date_range` 日期筛选 |
| `list_todo_workflows` | 待办流程列表 | 需后台授权 |
| `list_my_workflows` | 我的请求列表 | 需后台授权 |
| `list_processed_workflows` | 已办流程列表 | 需后台授权 |
| `query_employee` | 查询人员信息 | 需后台授权 |

### 日期筛选参数

`date_range` 可选值：

| 值 | 含义 |
|----|------|
| `TODAY` | 今天 |
| `CURRENT_WEEK` | 本周 |
| `CURRENT_MONTH` | 本月 |
| `CURRENT_SEASON` | 本季度 |
| `CURRENT_YEAR` | 本年 |
| `PRE_MONTH` | 上一月 |
| `PRE_YEAR` | 上一年 |

## 泛微后台配置

### 获取应用凭证

1. 登录 E10 后台管理中心
2. 进入 **开放平台 → 开发者资料**，获取 `corpid`
3. 进入 **开放平台 → 应用管理**，创建应用，获取 `app_key` 和 `app_secret`

### 授权 API 权限

路径：**E10 后台 → 开放平台 → 应用管理 → 应用详情 → API 权限**

需要授权的接口：

| 接口 | 必需 | 用途 |
|------|------|------|
| `getAllWorkflowRequestList` | 是 | 查询流程列表 |
| `getWorkflowRequest` | 是 | 获取流程详情 |
| `getToDoWorkflowRequestList` | 否 | 查询待办列表 |
| `getMyWorkflowRequestList` | 否 | 查询我的请求 |
| `getProcessedWorkflowRequestList` | 否 | 查询已办列表 |
| `queryEmployee` | 否 | 查询人员信息 |

### 获取用户 ID

E10 的 `userId` 是长数字格式（如 `1234567890123456789`），获取方式：

- 在 E10 后台 → 人员管理中查看用户详情
- 或授权 `queryEmployee` 接口后通过 API 查询

## 技术架构

```
weaver-mcp/
├── weaver_mcp/               # Python 包
│   ├── __init__.py
│   ├── __main__.py           # 入口点 (python -m weaver_mcp)
│   ├── config.py             # 配置加载
│   ├── weaver_client.py      # 泛微 API 客户端
│   └── main.py               # MCP 工具定义
├── .env                      # 实际配置（不提交）
├── .env.example              # 配置模板
├── mcp-config.example.json   # MCP 客户端配置示例
├── pyproject.toml            # Python 打包配置
├── requirements.txt          # 依赖清单
├── setup.bat / setup.sh      # 一键安装脚本
└── README.md
```

### API 端点

| 类型 | 路径 | 方法 |
|------|------|------|
| OAuth2 授权 | `/openserver/oauth2/authorize` | GET |
| OAuth2 Token | `/openserver/oauth2/access_token` | POST |
| 流程列表 | `/papi/openapi/api/workflow/list/paService/v1/getAllWorkflowRequestList` | POST |
| 流程详情 | `/papi/openapi/api/workflow/core/paService/v1/getWorkflowRequest` | GET |
| 人员查询 | `/papi/openapi/api/hrm/restful/queryEmployee` | POST |

## 环境要求

- Python 3.10+
- 网络可访问泛微 OA 服务器