内容
# Cordel
自托管的看板工具，适用于您的项目待办事项 — 设计用于直接由 Claude Code 等代理通过 MCP 查询和移动，无需依赖静态 `TODO.md` 文件。
您正在处理的项目的实时待办事项/看板。您在本地注册一个项目（通过 MCP），它就会获得自己的看板（待办/进行中/已完成）— 实时更新（SSE），因此如果有人（您、另一个标签页、通过 API 的 Claude Code 等代理）移动一张卡片，所有查看看板的人都会看到变化，无需刷新页面。
自托管：没有共享的公共实例或用户账户 — 每个人都部署自己的实例（本地或自己的服务器）并独立使用，无需登录。
卡片是 **本地待办事项** — 存储在实例自己的 SQLite 数据库中。
## 技术栈
Next.js 16（应用路由器，全栈 — 无单独后端）+ Prisma 7 + SQLite + 服务器发送事件用于实时更新。使用 [rough.js](https://roughjs.com/) 进行手绘风格设计。
## 本地运行
前提条件：Node 22+，pnpm。
```bash
pnpm install
cp .env.example .env
```
```bash
npx prisma migrate deploy # 创建本地 SQLite 数据库（dev.db，在项目根目录）
pnpm dev
```
在 [http://localhost:3000](http://localhost:3000) 打开。
## 使用 Docker 运行（推荐自托管）
```bash
cp .env.example .env
docker compose up -d --build
```
这会构建镜像，自动运行迁移到持久卷（`cordel-data`），并在端口 3000 上启动应用。数据在 `docker compose restart`/`down`（不带 `-v`）和镜像重建后仍然存在。
要更新代码后：
```bash
docker compose up -d --build
```
## 连接 Claude Code（MCP）
项目的原始想法：Claude Code 不检查本地 `TODO.md` 文件，而是直接查询和移动 Cordel 的卡片 — 在任何看板中，任何项目，无需复制/粘贴。
这通过 `mcp-server/` 中的 MCP 服务器实现，该服务器通过 API 使用令牌与您的实例通信。
项目仅在您（或代理，应您的请求）注册正在处理的本地项目时才会进入 Cordel — 不会自动从任何地方拉取：
- `scan_local_projects` — 给定根目录（例如 `~/Projects`），列出包含 `.git` 的子文件夹（项目候选）。仅列出，不注册任何内容。
- `add_local_project` — 注册本地项目（名称 + 绝对路径），创建其看板。
- `delete_project` — 删除项目（及其看板），永久删除。
本地项目路径仅作为数据库中的引用保存 — 应用永远不会打开或读取目录内容，因此无需为此配置 Docker 卷。
MCP 服务器已经包含 `instructions` 和 `annotations`，标记哪些工具是可逆的（本地看板，直接操作无问题）和哪些是永久的（`delete_card`，`delete_project` — 代理必须在操作前确认）。这对任何连接的人都是自动的，无需任何配置。
### 1. 生成 API 令牌
应用运行时，前往 **Tokens**（右上角）或直接访问 `/settings/tokens`，输入名称并点击“生成令牌”。复制显示的值 — 它只显示一次，之后无法恢复（只能撤销并在同一页面生成另一个）。
### 2. 在 Claude Code 中注册
```bash
./scripts/connect-claude.sh <步骤 1 中的令牌>
```
这会构建 `mcp-server/` 并运行 `claude mcp add` 命令。如果实例不在 `http://localhost:3000`，请将 URL 作为第二个参数传递：`./scripts/connect-claude.sh <令牌> https://cordel.seu-dominio.com`。
从现在开始，在任何 Claude Code 会话（在此项目或任何其他项目中），它都可以使用 Cordel 工具 — 可以请求“列出 Cordel 仓库”或“在 X 看板中创建卡片”，它已经知道如何调用正确的工具。
## 环境变量
参见 `.env.example` — 所有变量都已注释。摘要：
| 变量 | 用途 |
|---|---|
| `DATABASE_URL` | SQLite 文件路径。在 Docker 中，相对于项目根目录（非 `prisma/`）。 |
## 项目状态
本项目在其自己的 `.claude/CONTEXT.md` 和 `.claude/TODO.md` 中记录了其自身的上下文和待办事项 — 在贡献之前值得阅读。
