# Task Manager MCP Server

任务管理 MCP（Model Context Protocol，模型上下文协议）Server，纯 JavaScript 实现，无原生模块依赖。

配合 [Electron 任务管理桌面应用](https://github.com/2000sister/xx-task) 使用，让 AI 能够直接操作你的任务数据库。

---

## 为什么选择纯 JS 实现？

原方案使用 `better-sqlite3`（C++ 原生模块），该模块编译绑定特定 Node.js ABI 版本：
- Electron 33.x → NODE_MODULE_VERSION **130**
- Node.js 20.x → NODE_MODULE_VERSION **127**

两者不兼容，导致安装后用户无法用普通 `node` 运行 MCP Server。

本方案使用 `sql.js`（SQLite 的 WebAssembly 编译），**零原生依赖**，任何 Node.js 版本直接运行。

---

## 特性

- **零原生依赖**：使用 `sql.js`，无需 rebuild，开箱即用
- **与桌面应用共享数据库**：读写同一个 SQLite 文件，数据实时同步
- **15 个 MCP Tools**：覆盖任务、标签、分类、项目的完整 CRUD 操作
- **参数校验**：使用 `zod` 严格校验输入参数
- **完整的错误处理**：操作失败返回清晰的错误信息

---

## 项目结构

```
task-manager-mcp/
├── src/
│   ├── index.ts             # MCP Server 入口（stdio 传输）
│   ├── database.ts          # sql.js 数据库管理（核心适配层）
│   ├── types.ts             # 数据类型定义
│   └── tools/               # MCP Tools（按模块组织）
│       ├── task.tools.ts    # 6 个任务 tools
│       ├── tag.tools.ts     # 3 个标签 tools
│       ├── category.tools.ts # 3 个分类 tools
│       └── project.tools.ts # 3 个项目 tools
│
├── package.json
├── tsconfig.json
└── README.md
```

---

## 安装

### 环境要求

- Node.js >= 18
- npm >= 8

### 安装依赖

```bash
cd task-manager-mcp
npm install
```

> 无需 rebuild！`sql.js` 是纯 JavaScript，直接安装即可使用。

---

## 使用方式

### 开发模式（tsx 直接运行）

```bash
npm run dev
```

### 生产模式

```bash
npm run build    # TypeScript 编译到 dist/
npm start        # node dist/index.js
```

---

## 数据库路径

MCP Server 通过环境变量 `TASK_MANAGER_DB_PATH` 指定数据库文件位置。

| 操作系统 | 默认路径 |
|----------|----------|
| Windows | `%APPDATA%/task-manager/taskmanager.db` |
| macOS | `~/Library/Application Support/task-manager/taskmanager.db` |

> **注意**：首次使用前需要先运行一次 Electron 桌面应用（[xx-task](../xx-task/)），让主进程初始化数据库表结构。MCP Server 不会自动建表。

---

## 数据同步策略

MCP Server 与 Electron 应用共享同一个 SQLite 文件，采用以下策略确保数据一致性：

```
每次工具调用：
  读取文件 → 加载到内存（sql.js） → 执行操作 → 写回文件（如有写操作） → 关闭
```

- 每次操作都从磁盘读取最新数据，避免缓存过期
- 写操作完成后立即导出到磁盘
- 任务管理数据量小（通常 < 1MB），性能无影响
- SQLite WAL（Write-Ahead Logging）模式支持并发读写

---

## 测试

### 使用 MCP Inspector（推荐）

```bash
npx @modelcontextprotocol/inspector npm run dev
```

会打开 Web UI，可以：
- 查看所有注册的 tools 列表
- 手动调用每个 tool 并查看返回结果
- 测试参数校验

### 手动 stdio 测试

```bash
npm run dev
# 然后在另一个终端输入 JSON-RPC 消息：
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx tsx src/index.ts
```

---

## 配置到 AI 客户端

### Claude Desktop

编辑配置文件 `%APPDATA%\Claude\claude_desktop_config.json`：

**生产模式（推荐）**：
```json
{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["C:/Users/<你的用户名>/task-manager-mcp/dist/index.js"],
      "env": {
        "TASK_MANAGER_DB_PATH": "C:/Users/<你的用户名>/AppData/Roaming/task-manager/taskmanager.db"
      }
    }
  }
}
```

**开发模式**：
```json
{
  "mcpServers": {
    "task-manager": {
      "command": "npx",
      "args": ["tsx", "C:/Users/<你的用户名>/task-manager-mcp/src/index.ts"],
      "env": {
        "TASK_MANAGER_DB_PATH": "C:/Users/<你的用户名>/AppData/Roaming/task-manager/taskmanager.db"
      }
    }
  }
}
```

### Cursor / Windsurf

找到 MCP 设置入口，添加上述配置即可。

---

## 可用 Tools 列表

### 任务管理（6 个）

| Tool | 参数 | 说明 |
|------|------|------|
| `task_list` | status?, project_id?, tag_id?, keyword? | 获取任务列表，支持多种筛选 |
| `task_get` | id | 获取任务详情（含标签和项目） |
| `task_add` | title, description?, status?, ... | 添加新任务 |
| `task_update` | id, title?, description?, ... | 更新任务（只需传修改字段） |
| `task_change_status` | id, status | 变更任务状态 |
| `task_delete` | id | 删除任务（不可恢复） |

### 标签管理（3 个）

| Tool | 参数 | 说明 |
|------|------|------|
| `tag_list` | 无 | 获取所有标签 |
| `tag_create` | name, color? | 创建标签 |
| `tag_delete` | id | 删除标签 |

### 分类管理（3 个）

| Tool | 参数 | 说明 |
|------|------|------|
| `category_list` | 无 | 获取所有分类（含项目列表） |
| `category_create` | name, description? | 创建分类 |
| `category_delete` | id | 删除分类（级联删除项目） |

### 项目管理（3 个）

| Tool | 参数 | 说明 |
|------|------|------|
| `project_list` | category_id?, keyword? | 获取项目列表，支持按名称关键词搜索 |
| `project_create` | name, category_id, description? | 创建项目 |
| `project_delete` | id | 删除项目 |

---

## 示例对话

配置好后，你可以对 AI 说：

**任务操作**：
- "帮我创建一个任务：完成项目报告，截止日期下周五"
- "列出所有进行中的任务"
- "把'完成项目报告'的状态改为进行中"
- "删除任务 ID 为 5 的任务"

**标签操作**：
- "创建一个标签：紧急，颜色红色 #ff0000"
- "显示所有标签"

**分类和项目**：
- "新建一个分类叫'工作'"
- "在'工作'分类下创建一个'Q4 规划'项目"
- "显示所有分类和项目"

---

## 技术栈

| 技术 | 用途 |
|------|------|
| Node.js | 运行环境 |
| TypeScript | 类型安全 |
| sql.js | SQLite 数据库（纯 JS/WASM） |
| @modelcontextprotocol/sdk | MCP 协议 SDK |
| zod | 参数校验 |
| tsx | 开发模式 TypeScript 运行 |

---

## 与 xx-task 的关系

| 项目 | 职责 | 数据库驱动 |
|------|------|-----------|
| [xx-task](../xx-task/) | Electron 桌面应用，UI 交互 | better-sqlite3（原生模块） |
| task-manager-mcp（本仓库） | MCP Server，AI 操作接口 | sql.js（纯 JS/WASM） |

两个项目共享同一个 SQLite 数据库文件，通过 WAL 模式实现并发安全。

---

## 构建脚本

| 命令 | 说明 |
|------|------|
| `npm run dev` | 开发模式（tsx 直接运行） |
| `npm run build` | 编译 TypeScript 到 dist/ |
| `npm start` | 生产模式运行 |

---

## License

MIT