Viban

🚀 Viban

一款集成MCP服务器的看板，用于人工智能辅助任务管理

Viban是一个轻量级的TypeScript看板，它通过模型上下文协议（MCP）与人工智能编码助手集成。它使Claude、Cursor或Antigravity等人工智能工具能够以编程方式管理开发任务。本项目在Antigravity（Opus 4.5 + Gemini 3 Flash）的人工智能支持下编写。

✨ 主要特性

• 🎯 四个看板列：待办事项积压 → 待办 → 审核 → 已完成
• 🌐 Web用户界面：可在http://localhost:3000 访问可视化看板
• 🌙 浅色/深色模式：可在不同主题之间切换
• 🤖 MCP服务器：提供9种工具用于人工智能集成
• 📁 基于文件的存储：任务存储在JSON文件中，配置存储在YAML文件中
• ⚡ 轻量级：无需数据库

🚀 快速开始

选项1：本地运行（npm）

# 克隆仓库
git clone https://github.com/yourusername/viban.git
cd viban

# 安装依赖
npm install

# 构建项目
npm run build

# 交互式运行（提示输入项目路径）
node dist/index.js

# 或者作为MCP服务器运行（使用上一个项目或当前目录）
node dist/index.js --mcp

选项3：开发模式

# 在开发模式下运行（交互式）
npm run dev

# 或者在开发模式下作为MCP服务器运行
npm run dev -- --mcp

📦 安装指南

Viban将其配置存储在项目目录中的 .config-viban.yml 文件中：

boardName: "My Project"
tasksFile: "tasks.json"
createdAt: "2026-01-11T11:20:30+01:00"

任务存储在 tasks.json 文件中：

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication",
    "description": "Add login/logout functionality",
    "column": "todo",
    "priority": "high",
    "createdAt": "2026-01-11T11:20:30+01:00",
    "updatedAt": "2026-01-11T11:20:30+01:00"
  }
]

📚 详细文档

MCP集成

Claude Desktop

添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "viban": {
      "command": "node",
      "args": ["/absolute/path/to/viban/dist/index.js", "--mcp"],
      "env": {
        "VIBAN_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Cursor

添加到MCP设置中：

{
  "viban": {
    "command": "node",
    "args": ["/absolute/path/to/viban/dist/index.js", "--mcp"],
    "env": {
      "VIBAN_PROJECT_PATH": "/path/to/your/project"
    }
  }
}

Antigravity

添加到Antigravity MCP设置中：

{
  "mcpServers": {
    "viban": {
      "command": "node",
      "args": [
        "c:/Users/Seb/Documents/viban/dist/index.js",
        "--mcp"
      ],
      "env": {
        "VIBAN_PROJECT_PATH": "C:/Users/Seb/Documents/viban_test"
      }
    }
  }
}

⚠️ 重要提示

MCP服务器使用 VIBAN_PROJECT_PATH 环境变量，若未设置则回退到交互式模式下最后选择的项目路径。

可用的MCP工具

可用的MCP资源

人工智能工作流程示例

1. 人工智能获取当前任务：

"Show me the current TODO tasks"
→ 调用 get_todo_tasks

2. 人工智能处理任务：

"Work on task: Implement login functionality"
→ 人工智能实现该功能

3. 人工智能标记任务以供审核：

"I've completed the task, move it to review"
→ 调用 move_to_review(id)

🔧 技术细节

开发

# 安装依赖
npm install

# 在开发模式下运行
npm run dev -- /path/to/project

# 运行测试
npm test

# 构建生产版本
npm run build

项目结构

viban/
├── src/
│   ├── index.ts          # CLI入口点
│   ├── mcp-server.ts     # MCP服务器实现
│   ├── board/
│   │   ├── types.ts      # TypeScript接口
│   │   ├── board.ts      # 看板管理逻辑
│   │   └── storage.ts    # JSON文件存储
│   └── config/
│       └── config.ts     # YAML配置解析器
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
└── README.md

📄 许可证

MIT