内容
# 看板管理工具
[印尼语版本](./README_ID.md)
一个功能齐全的看板工具，集成 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，允许 AI 编程代理以编程方式管理项目和任务。
## 目录
- [技术栈](#tech-stack)
- [功能](#features)
- [快速入门](#getting-started)
- [MCP 服务器](#mcp-server)
- [可用工具](#available-tools)
- [可用资源](#available-resources)
- [独立运行 MCP 服务器](#run-mcp-server-standalone)
- [配置 MCP 客户端](#configure-mcp-client)
- [使用示例](#usage-example)
- [脚本](#scripts)
- [项目结构](#project-structure)
- [AI 代理集成](#ai-agent-integration)
- [系统提示](#system-prompt)
- [技能（反重力）](#skill-antigravity)
- [许可证](#license)
## 技术栈
| 层级 | 技术 |
| ----------- | --------------------------- |
| 框架 | Next.js 16 (应用路由器) |
| 语言 | TypeScript |
| 数据库 | SQLite + Drizzle ORM |
| 用户界面 | shadcn/ui + Tailwind CSS v4 |
| 状态 | Zustand |
| 拖拽 | @dnd-kit |
| MCP | @modelcontextprotocol/sdk |
## 功能
- **看板** — 在待办事项、进行中、已完成等之间拖拽任务
- **仪表盘** — 汇总卡片、饼图（状态/优先级）、14 天趋势条形图、项目分解
- **子任务** — 清单式子任务，带有进度条
- **标签** — 自定义颜色标签，每个项目
- **评论** — 带有时间戳的评论线程，针对任务
- **活动日志** — 任务更改的历史记录
- **搜索和筛选** — 实时搜索 + 优先级筛选，针对看板
- **CSV 导出** — 导出所有任务或每个项目
- **暗黑模式** — 默认启用
- **MCP 服务器** — 13 种工具 + 4 种资源，用于 AI 代理集成
## 快速入门
### 前置条件
- Node.js 18+
- npm
### 安装
```bash
git clone https://github.com/dzikrihilman/kanban-mcp.git
cd kanban-mcp
npm install
```
### 数据库设置
```bash
npm run db:generate
npm run db:migrate
```
### 运行开发服务器
```bash
npm run dev
```
打开 [http://localhost:3000](http://localhost:3000)。
## MCP 服务器
MCP 服务器为 AI 编程代理（Claude, Cursor, Windsurf 等）提供项目和任务管理工具。
### 可用工具
| 工具 | 描述 |
| ----------------------- | -------------------------------------- |
| `list_projects` | 列出所有项目，包含任务数量 |
| `get_project` | 获取项目详情 |
| `create_project` | 创建新项目 |
| `update_project` | 更新项目字段 |
| `delete_project` | 删除项目和所有任务 |
| `list_tasks` | 列出任务（按状态/优先级筛选） |
| `get_task` | 获取任务，包含评论 |
| `create_task` | 创建任务，包含所有字段 |
| `update_task` | 更新任务，记录活动日志 |
| `delete_task` | 删除任务 |
| `move_task` | 在列之间移动任务 |
| `add_comment` | 添加评论到任务 |
| `search_tasks` | 按关键词搜索 |
| `get_dashboard_summary` | 获取仪表盘汇总统计 |
### 可用资源
| URI | 描述 |
| ----------------------------- | ------------------ |
| `kanban://projects` | 所有项目 |
| `kanban://project/{id}` | 项目详情 |
| `kanban://project/{id}/tasks` | 项目任务 |
| `kanban://task/{id}` | 任务，包含评论 |
### 独立运行 MCP 服务器
```bash
npm run mcp:start
```
### 配置 MCP 客户端
将以下内容添加到您的 MCP 客户端配置中：
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"kanban-mcp": {
"command": "npx",
"args": ["tsx", "/绝对路径/to/kanban-mcp/src/mcp-server/index.ts"]
}
}
}
```
**Cursor / Windsurf / Antigravity** (`mcp_config.json`):
```json
{
"mcpServers": {
"kanban-mcp": {
"command": "npx",
"args": ["tsx", "/绝对路径/to/kanban-mcp/src/mcp-server/index.ts"]
}
}
}
```
> 将 `/绝对路径/to/kanban-mcp` 替换为您的实际项目路径。
### 使用示例
配置完成后，您的 AI 代理可以：
```
"创建一个名为 'My App' 的新项目，并添加 3 个任务"
"将任务 X 移到进行中"
"显示仪表盘汇总"
"导出所有任务为 CSV"
```
## 脚本
| 脚本 | 描述 |
| --------------------- | --------------------------- |
| `npm run dev` | 启动 Next.js 开发服务器 |
| `npm run build` | 生产环境构建 |
| `npm run start` | 启动生产环境服务器 |
| `npm run mcp:start` | 启动 MCP 服务器（标准输入） |
| `npm run db:generate` | 生成 Drizzle 迁移文件 |
| `npm run db:migrate` | 运行数据库迁移 |
## 项目结构
```
src/
├── app/
│ ├── api/ # API 路由
│ │ ├── activity/ # 活动日志
│ │ ├── analytics/ # 分析数据
│ │ ├── comments/ # 评论 CRUD
│ │ ├── dashboard/ # 仪表盘汇总
│ │ ├── export/ # CSV 导出
│ │ ├── labels/ # 标签 CRUD
│ │ ├── projects/ # 项目 CRUD
│ │ ├── task-labels/ # 任务-标签关联
│ │ └── tasks/ # 任务 CRUD + 重新排序
│ ├── projects/[id]/ # 看板页面
│ └── page.tsx # 仪表盘页面
├── components/
│ ├── charts/ # 饼图，迷你条形图
│ ├── dashboard/ # 仪表盘视图
│ ├── kanban/ # 看板，列，卡片，筛选条等
│ ├── layout/ # 应用侧边栏
│ └── ui/ # shadcn/ui 组件
├── hooks/
│ └── useKanbanStore.ts # Zustand 存储
├── lib/db/
│ ├── schema.ts # Drizzle 模式
│ ├── index.ts # 数据库客户端
│ └── migrate.ts # 迁移运行器
├── mcp-server/
│ ├── index.ts # MCP 服务器（13 种工具，4 种资源）
│ └── db-client.ts # 独立数据库客户端，用于 MCP
└── types/
└── index.ts # 共享类型
```
## AI 代理集成
要使您的 AI 代理自动跟踪每个开发任务，使用看板 MCP，您可以添加系统提示和/或安装技能。
### 系统提示
将 [`docs/SYSTEM_PROMPT.md`](./docs/SYSTEM_PROMPT.md) 中的系统提示添加到您的 AI 代理配置中。这指示代理：
- 在开始任何工作之前自动创建任务
- 在工作过程中更新任务状态
- 添加评论以记录技术决策
- 将复杂工作分解为子任务
- 使用一致的标题格式（[功能]，[修复]，[重构]，[文档]，[测试]）
参见文件，了解 Claude Desktop、Cursor、Windsurf 和 Antigravity 的设置说明。
### 技能（反重力）
复制 [`docs/SKILL.md`](./docs/SKILL.md) 到您的 Antigravity 技能文件夹：
```bash
mkdir -p ~/.gemini/antigravity/skills/kanban-mcp
cp docs/SKILL.md ~/.gemini/antigravity/skills/kanban-mcp/SKILL.md
```
安装后，代理将自动激活技能，当它检测到关键词如 `任务`、`项目`、`看板`、`跟踪`、`进度`、`待办` 或 `待处理`。
参见 [`docs/SKILL.md`](./docs/SKILL.md) 以获取完整的工作流程参考和规则。
## 许可证
MIT
