# mcp-workflow-manager

**Repository Path**: wei_bin_9966/mcp-workflow-manager

## Basic Information

- **Project Name**: mcp-workflow-manager
- **Description**: 工作流管理MCP，配合使用， 可以实现多任务并行处理，包含数据存储，简单好用~
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-10
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 工作流管理系统

一个基于 Go 语言的 MCP 服务器，提供独立于 Claude 对话上下文的持久化任务工作流管理系统。

## 功能特性

### 核心功能（v1.0）

- ✅ **工作流管理**
  - 创建工作流（AI 辅助生成任务列表）
  - 查看所有工作流列表
  - 查看工作流详情
  - 删除/归档工作流

- ✅ **智能任务管理**
  - 智能推荐当前应执行的任务（自动计算依赖关系）
  - 获取任务详细信息
  - 标记任务完成
  - 任务执行上下文自动汇总（收集依赖任务产出）
  - 任务依赖关系图可视化

- ✅ **数据持久化**
  - 工作流数据存储（JSON）
  - 操作历史记录
  - 自动备份机制

- ✅ **AI 辅助功能**
  - 根据功能描述自动生成任务列表
  - 智能推荐任务粒度（粗/中/细）
  - 任务依赖关系自动推断
  - 预估任务耗时

### 🆕 v2.0 新功能 - 上下文优化

- ✅ **工作流级别上下文管理** - 减少 85-90% 的 token 消耗
  - 文件摘要存储（存储关键信息而非完整文件内容）
  - 任务输出自动缓存和引用
  - 数据库 schema 缓存
  - 代码规范缓存
  - 跨任务上下文共享

- ✅ **任务分组功能**
  - 将相关任务分组，在同一对话中完成
  - 减少上下文重复加载
  - 支持分组状态管理

### 🚀 v3.0 新功能 - 极致 Token 优化

- ✅ **精简版 API** - 减少 85-95% 的 token 消耗
  - `workflow_get_current_task_minimal` - 只返回必要的任务信息
  - `workflow_list_minimal` - 精简的工作流列表
  - 移除冗余字段，大幅减少数据传输量

- ✅ **按需加载（懒加载）**
  - `workflow_get_file_summary` - 按需获取文件摘要
  - `workflow_get_task_output` - 按需获取任务详细输出
  - `workflow_get_context_references` - 只返回引用列表
  - 避免一次性加载所有上下文

- ✅ **智能摘要生成**
  - 任务完成时自动生成精简摘要（前 200 字）
  - 自动提取关键决策（包含"决策"、"关键"、"重要"等关键词的句子）
  - Summary 用于快速引用，完整 Notes 按需获取

**Token 消耗对比：**
- 旧版：获取当前任务 ~45,000 tokens
- 新版：获取当前任务 ~2,000 tokens
- **节省：95%**

详见 [TOKEN_OPTIMIZATION.md](TOKEN_OPTIMIZATION.md)

## 快速开始

### 安装依赖

```bash
go mod download
```

### 编译

```bash
# 开发环境编译
go build -o bin/workflow-manager cmd/server/main.go

# 或使用 make（如果有 Makefile）
make build
```

### 运行

```bash
# 使用默认数据目录
./bin/workflow-manager

# 指定数据目录
./bin/workflow-manager -data-dir=/path/to/data
```

### MCP 配置

在 Claude Desktop 或 Claude Code 的配置文件中添加：

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "workflow-manager": {
      "command": "/path/to/workflow-manager",
      "args": ["-data-dir", "/path/to/project/.workflow"]
    }
  }
}
```

#### Claude Code (`~/.config/claude-code/mcp.json`)

```json
{
  "mcp": {
    "servers": {
      "workflow-manager": {
        "command": "/path/to/workflow-manager",
        "args": ["-data-dir", "${workspaceFolder}/.workflow"],
        "env": {
          "LOG_LEVEL": "info"
        }
      }
    }
  }
}
```

## 使用示例

### 1. 创建工作流（推荐：先创建空工作流）

```javascript
// 方式1：创建空工作流（推荐）
// AI 会先创建工作流框架，然后逐步添加任务
workflow_create({
  "feature_name": "用户认证系统",
  "description": "实现完整的用户认证系统，包括注册、登录、密码重置等功能",
  "granularity": "medium"
  // 不提供 tasks，将创建空工作流
})

// 返回：
{
  "status": "success",
  "message": "空工作流创建成功，请使用 workflow_add_task 添加任务",
  "workflow_id": "abc-123",
  "task_count": 0,
  "next_steps": [
    "使用 workflow_add_task 添加任务到工作流",
    "或者让 AI 分析功能需求并生成任务列表"
  ]
}

// 方式2：直接提供任务列表创建（可选）
workflow_create({
  "feature_name": "用户认证系统",
  "description": "实现完整的用户认证系统",
  "tasks": [
    {
      "name": "设计数据库表结构",
      "type": "database",
      "description": "...",
      // ...
    }
  ]
})
```

### 1.1 添加任务到工作流

```javascript
// 逐步添加任务
workflow_add_task({
  "workflow_id": "abc-123",
  "task": {
    "name": "设计数据库表结构",
    "type": "database",
    "description": "设计 users 表，包含基本字段和索引",
    "priority": "high",
    "order": 1,
    "estimated_minutes": 30
  }
})
```

### 2. 查看当前任务

```bash
# 使用 workflow_get_current_task 工具
{
  "workflow_id": "abc-123"
}
```

### 3. 获取任务上下文

```bash
# 使用 workflow_get_task_context 工具
{
  "workflow_id": "abc-123",
  "task_id": "task-1"
}
```

### 4. 完成任务

```bash
# 使用 workflow_complete_task 工具
{
  "workflow_id": "abc-123",
  "task_id": "task-1",
  "created_files": ["/path/to/file1", "/path/to/file2"],
  "notes": "实现了基本的认证逻辑，使用了 JWT 进行 token 管理"
}
```

## 可用工具

### 工作流管理
- `workflow_create` - 创建新的工作流
- `workflow_list` - 列出所有工作流
- `workflow_list_minimal` 🆕 - 列出所有工作流（精简版，减少 95% token）
- `workflow_get_detail` - 获取工作流详细信息
- `workflow_delete` - 删除（归档）工作流

### 任务管理
- `workflow_get_current_task` - 获取当前应执行的任务
- `workflow_get_current_task_minimal` 🆕 - 获取当前任务（精简版，推荐使用，减少 95% token）
- `workflow_complete_task` - 标记任务完成（🆕 自动生成智能摘要）
- `workflow_get_task_context` - 获取任务执行上下文
- `workflow_show_dependency_graph` - 显示任务依赖关系图
- `workflow_add_task` - 向工作流添加新任务
- `workflow_edit_task` - 编辑未完成的任务
- `workflow_delete_task` - 删除未完成的任务

### 🆕 上下文管理（v2.0）
- `workflow_add_file_summary` - 添加文件摘要到工作流上下文
- `workflow_get_context` - 获取工作流上下文（文件摘要、任务输出等）
- `workflow_get_context_references` 🆕 - 获取上下文引用列表（只返回引用，减少 98% token）
- `workflow_get_file_summary` 🆕 - 按需获取指定文件摘要
- `workflow_get_task_output` 🆕 - 按需获取指定任务详细输出
- `workflow_add_db_schema` - 添加数据库表结构到上下文

### 🆕 任务分组（v2.0）
- `workflow_create_task_group` - 创建任务分组
- `workflow_get_task_groups` - 获取工作流的所有任务分组

## 可用 Prompts

- `generate_tasks` - AI 辅助生成工作流任务列表

## 项目结构

```
mcp-workflow-manager/
├── cmd/
│   └── server/
│       └── main.go              # 主程序入口
├── internal/
│   ├── mcp/
│   │   ├── server.go           # MCP 服务器实现
│   │   ├── tools.go            # 工具定义和处理
│   │   └── prompts.go          # Prompt 定义
│   ├── workflow/
│   │   ├── types.go            # 数据结构定义
│   │   ├── manager.go          # 工作流管理核心逻辑
│   │   └── ai_assistant.go     # AI 辅助功能
│   └── storage/
│       ├── storage.go          # 存储接口定义
│       └── json_storage.go     # JSON 文件存储实现
├── configs/
│   └── config.yaml             # 配置文件
├── go.mod
└── README.md
```

## 技术栈

- **开发语言**: Go 1.21+
- **MCP SDK**: `github.com/mark3labs/mcp-go`
- **数据存储**: JSON 文件
- **UUID**: `github.com/google/uuid`

## 💡 AI 使用工作流的最佳实践

### 推荐流程（避免工作流创建失败）

```
步骤1: 创建空工作流
→ workflow_create({
    feature_name: "功能名称",
    description: "详细描述"
  })
  // 不提供 tasks 参数

步骤2: AI 分析需求并逐步添加任务
→ workflow_add_task({ workflow_id, task: {...} })
→ workflow_add_task({ workflow_id, task: {...} })
→ workflow_add_task({ workflow_id, task: {...} })

步骤3: (可选) 创建任务分组
→ workflow_create_task_group({
    workflow_id,
    name: "数据层开发",
    task_ids: ["task1", "task2", "task3"]
  })

步骤4: (可选) 添加上下文信息
→ workflow_add_file_summary({ workflow_id, ... })
→ workflow_add_db_schema({ workflow_id, ... })

步骤5: 开始执行任务
→ workflow_get_current_task({ workflow_id })
→ workflow_complete_task({ workflow_id, task_id, ... })
```

### ❌ 常见错误（避免）

```javascript
// 错误：AI 尝试在 workflow_create 时提供复杂的 tasks 数组
// 这经常导致格式错误或 AI 以为创建成功但实际失败
workflow_create({
  feature_name: "用户管理",
  tasks: [/* 复杂的任务数组，AI 可能格式化错误 */]
})
```

### ✅ 正确方式

```javascript
// 1. 先创建空工作流
const result = workflow_create({
  feature_name: "用户管理",
  description: "完整的用户CRUD功能"
})
// 得到 workflow_id

// 2. 逐个添加任务（AI 更容易正确执行）
workflow_add_task({
  workflow_id: result.workflow_id,
  task: {
    name: "设计数据库",
    type: "database",
    description: "设计 users 表"
  }
})

workflow_add_task({
  workflow_id: result.workflow_id,
  task: {
    name: "创建 Entity",
    type: "backend",
    description: "创建 User 实体类",
    dependencies: ["上一个任务的ID"]
  }
})
```

## 🎯 v2.0 上下文优化使用指南

### 为什么需要上下文优化？

在执行包含多个任务的工作流时，传统方式会导致：
- ✅ 每个任务都重复读取相同的文件 → **token 消耗巨大**
- ✅ 数据库 schema 被重复查询
- ✅ 代码规范被重复获取
- ✅ 子任务 agent 无法共享上下文

### 解决方案：工作流级别上下文共享

#### 1. 添加文件摘要（而非完整内容）

```javascript
// ❌ 传统方式：每个任务都读取完整文件（5000 tokens）
task1: 读取 User.java (5000 tokens)
task2: 再次读取 User.java (5000 tokens)
task3: 又读取 User.java (5000 tokens)
总计：15000 tokens

// ✅ 使用文件摘要（500 tokens）
工作流开始时添加一次摘要：
workflow_add_file_summary({
  workflow_id: "xxx",
  file_path: "src/entity/User.java",
  file_type: "entity",
  description: "用户实体类",
  fields: ["id: Long", "username: String", "email: String"],
  methods: ["getters/setters", "validate()"],
  dependencies: ["UserDTO", "UserRepository"]
})

task1,2,3: 从 workflow_get_context 获取摘要 (500 tokens 一次性)
总计：500 tokens → 节省 96%
```

#### 2. 任务分组：在同一对话中完成多个任务

```javascript
// ❌ 传统方式：每个任务一个 agent
任务1: 设计数据库 → 新 agent → 重新加载上下文
任务2: 创建 Entity → 新 agent → 重新加载上下文
任务3: 创建 Service → 新 agent → 重新加载上下文

// ✅ 使用任务分组
workflow_create_task_group({
  workflow_id: "xxx",
  name: "数据层开发",
  description: "数据库、Entity、Repository 相关任务",
  task_ids: ["task1_id", "task2_id", "task3_id"]
})

// 在同一个对话中完成所有3个任务
// 上下文只加载一次，后续任务复用
```

#### 3. 数据库 Schema 缓存

```javascript
// 工作流开始时缓存 schema
workflow_add_db_schema({
  workflow_id: "xxx",
  table_name: "users",
  schema: {
    columns: [...],
    indexes: [...],
    relations: [...]
  }
})

// 后续任务直接从上下文获取
const context = workflow_get_context({ workflow_id: "xxx" });
// 无需再次查询数据库
```

#### 4. 自动缓存任务输出

```javascript
// 任务完成时，输出自动添加到上下文
workflow_complete_task({
  workflow_id: "xxx",
  task_id: "task1",
  created_files: ["User.java"],
  notes: "使用 Lombok 简化代码"
})

// 后续任务可以引用前面任务的输出
const context = workflow_get_context({ workflow_id: "xxx" });
context.task_outputs["task1"].notes // "使用 Lombok 简化代码"
```

### 实际使用流程示例

```
1. 创建工作流（15个任务：用户管理模块）

2. 工作流初始化阶段：
   - 添加常用文件摘要（User.java, UserDTO.java, UserService.java）
   - 添加数据库 schema（users 表）
   - 添加代码规范到上下文

3. 创建任务分组：
   - 分组1：数据库层（任务1-3）
   - 分组2：业务层（任务4-8）
   - 分组3：接口层（任务9-12）
   - 分组4：测试文档（任务13-15）

4. 执行任务：
   - 在同一对话中完成分组1的所有任务
   - 使用 workflow_get_context 获取共享信息
   - 任务完成后输出自动缓存
   - 切换到分组2，继续在同一对话完成

5. Token 节省对比：
   - 传统方式：~150k tokens
   - 使用上下文优化：~20k tokens
   - 节省：85%+
```

### 最佳实践建议

1. **工作流开始时**：
   - 一次性添加所有可能用到的文件摘要
   - 缓存数据库 schema
   - 添加代码规范

2. **合理分组任务**：
   - 相关性强的任务分到一组
   - 每组3-5个任务为宜
   - 避免组内任务跨度太大

3. **优先使用摘要**：
   - 只有需要修改文件时才读取完整内容
   - 其他情况使用摘要即可

4. **充分利用任务输出**：
   - 在 notes 中记录关键决策
   - 后续任务可以引用这些决策

## 🚀 快速上手优化版工具

### 推荐使用流程（节省 95% Token）

```javascript
// 1. 获取当前任务（精简版）
const task = workflow_get_current_task_minimal({ workflow_id: "xxx" });
// 返回：2,000 tokens vs 旧版 45,000 tokens

// 2. 查看可用上下文
const refs = workflow_get_context_references({ workflow_id: "xxx" });
// 返回：500 tokens，只包含引用列表

// 3. 按需获取文件摘要
if (refs.available_files.includes("Controller.java")) {
  const file = workflow_get_file_summary({
    workflow_id: "xxx",
    file_path: "Controller.java"
  });
  // 返回：300 tokens，单个文件摘要
}

// 4. 完成任务（自动生成摘要）
workflow_complete_task({
  workflow_id: "xxx",
  task_id: "task-14",
  notes: "完整的实现说明...",
  created_files: ["Store.ts"]
});
// 系统自动生成 200 字摘要 + 提取关键决策
```

**Token 对比：**
- 使用优化工具：2,000 + 500 + 300 = **2,800 tokens**
- 使用旧版工具：45,000 + 30,000 + 5,000 = **80,000 tokens**
- **节省：96.5%**

更多详情请参考 [TOKEN_OPTIMIZATION.md](TOKEN_OPTIMIZATION.md)

---

## 开发计划

### ✅ V2.0 - 上下文优化（已完成）

- ✅ 工作流级别上下文管理
- ✅ 文件摘要存储
- ✅ 任务分组功能
- ✅ 数据库 schema 缓存
- ✅ 任务输出自动缓存

### ✅ V3.0 - 极致 Token 优化（已完成）

- ✅ 精简版 API（减少 85-95% token）
- ✅ 按需加载机制（懒加载）
- ✅ 智能摘要生成（自动提取关键决策）
- ✅ 上下文引用系统
- ✅ 完整的文档和迁移指南

### V4.0 - 增强功能（计划中）

- [ ] 工作流模板管理
- [ ] 任务进度可视化
- [ ] 工作流统计分析
- [ ] 导出工作流报告
- [ ] 多人协作支持
- [ ] AI 智能摘要升级（集成 LLM）

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 作者

MCP Workflow Manager Team