# Cronicle 定时调度 MCP Server

基于官方 [`modelcontextprotocol/python-sdk`](https://github.com/modelcontextprotocol/python-sdk) 的 `FastMCP` 实现，面向 Cherry Studio、Claude Desktop、Cursor 等 MCP 客户端提供 Cronicle 定时调度系统 API 工具。

## 已暴露工具

| 工具 | 说明 |
|---|---|
| `get_schedule` | 获取所有定时事件列表，支持 offset/limit 分页 |
| `get_event` | 根据事件 ID 或标题获取单个事件详细信息 |
| `create_event` | 创建新的定时事件 |
| `create_one_shot_event` | 创建一次性任务，执行后自动禁用或删除 |
| `update_event` | 更新已有事件的配置 |
| `delete_event` | 删除指定事件 |
| `get_event_history` | 获取指定事件的历史完成作业记录 |
| `get_history` | 获取所有事件的全局历史完成作业记录 |
| `run_event` | 立即手动触发事件执行，不等待定时调度 |
| `get_job_status` | 查询作业当前状态，包括进度、资源使用等 |
| `get_active_jobs` | 获取当前所有正在运行的活跃作业列表 |
| `update_job` | 更新运行中作业的配置（超时、重试、通知等） |
| `abort_job` | 强制中止一个正在运行的作业 |
| `get_master_state` | 获取调度器启停状态 |
| `update_master_state` | 启用或暂停整个调度系统 |

## 项目结构

```text
managing-cronicle-scheduler/
├── .env.example
├── .gitignore
├── AGENTS.md
├── README.md
├── pyproject.toml
└── src/
    └── managing_cronicle_scheduler/
        ├── __init__.py
        ├── __main__.py
        ├── client.py
        └── server.py
```

## 环境要求

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) 包管理器

## 配置

复制 `.env.example` 为 `.env`，填入 Cronicle 服务地址和 API Key：

```bash
cp .env.example .env
```

编辑 `.env`：

```env
CRONICLE_BASE_URL=https://cron.example.com
CRONICLE_API_KEY=your-32-character-hex-api-key
CRONICLE_DEFAULT_CATEGORY=cmp6jqxkx01
CRONICLE_DEFAULT_TARGET=allgrp
CRONICLE_DEFAULT_PLUGIN=urlplug
```

API Key 可在 Cronicle UI 的 API Keys Tab 中创建，需 32 位十六进制字符串。

`CRONICLE_DEFAULT_CATEGORY`、`CRONICLE_DEFAULT_TARGET`、`CRONICLE_DEFAULT_PLUGIN` 为 `create_event` 工具的默认值，可在调用时覆盖。

## 安装依赖

```bash
uv sync
```

## 启动

默认使用 `stdio` 传输，这是 MCP 客户端最常用的方式：

```bash
uv run managing-cronicle-scheduler
```

等价方式：

```bash
uv run python -m managing_cronicle_scheduler
```

## HTTP Transport 调试

如需 HTTP/SSE 方式启动：

```bash
uv run managing-cronicle-scheduler --transport sse --host 0.0.0.0 --port 8000
uv run managing-cronicle-scheduler --transport streamable-http --host 0.0.0.0 --port 8000
```

SSE 端点：`/sse`，Streamable HTTP 端点：`/mcp`。

## Cherry Studio 配置示例

```json
{
  "mcpServers": {
    "managing-cronicle": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/managing-cronicle-scheduler",
        "run",
        "managing-cronicle-scheduler"
      ],
      "env": {
        "CRONICLE_BASE_URL": "https://cron.example.com",
        "CRONICLE_API_KEY": "your-32-character-hex-api-key",
        "CRONICLE_DEFAULT_CATEGORY": "cmp6jqxkx01",
        "CRONICLE_DEFAULT_TARGET": "allgrp",
        "CRONICLE_DEFAULT_PLUGIN": "urlplug"
      }
    }
  }
}
```

通过 `env` 字段直接注入环境变量，无需 `.env` 文件。只有 `CRONICLE_BASE_URL` 和 `CRONICLE_API_KEY` 为必填，其余三项有默认值可省略。

如果配置界面是逐项填写：

- Command：`uv`
- Args：`--directory /absolute/path/to/managing-cronicle-scheduler run managing-cronicle-scheduler`
- Transport：`stdio`

## OpenCode 配置

### 本地模式（推荐）

使用 `opencode mcp add` 命令添加：

```bash
opencode mcp add
```

按提示输入：
- **名称**：`managing-cronicle`
- **类型**：`local`
- **命令**：`uv --directory /Users/wangjun/Workspace/boscloud/managing-cronicle-scheduler run managing-cronicle-scheduler`

也可以在 `~/.config/opencode/opencode.jsonc` 中直接配置：

```jsonc
"managing-cronicle": {
  "type": "local",
  "command": [
    "uv",
    "--directory",
    "/absolute/path/to/managing-cronicle-scheduler",
    "run",
    "managing-cronicle-scheduler"
  ],
  "env": {
    "CRONICLE_BASE_URL": "https://cron.example.com",
    "CRONICLE_API_KEY": "your-32-character-hex-api-key"
  }
}
```

### 远程模式

先启动 HTTP/SSE 服务：

```bash
uv run managing-cronicle-scheduler --transport sse --host 0.0.0.0 --port 8000
```

再在 `~/.config/opencode/opencode.jsonc` 中配置远程连接：

```jsonc
"managing-cronicle": {
  "type": "remote",
  "url": "http://localhost:8000/sse"
}
```

## 自测

### 1. 语法检查

```bash
uv run python -m compileall src
```

### 2. MCP Inspector 检查工具列表

```bash
npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/managing-cronicle-scheduler run managing-cronicle-scheduler
```

连接成功后应能看到 15 个工具。

### 3. 直接启动观察

```bash
uv run managing-cronicle-scheduler --log-level DEBUG
```

MCP `stdio` 服务启动后工具列表需要由 MCP 客户端发起 `tools/list` 才会显示。