AI导哈

看板协议服务器

一个用于Life System看板API的模型上下文协议服务器，支持通过自然语言与看板交互。

  • by the-ansible
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 the-ansible/kanban-mcp-server

使用说明

看板MCP服务器

生命系统看板API的MCP（模型上下文协议）服务器。使Claude Code能够使用自然语言与看板板进行交互。

快速开始

联合启动（推荐）

使用单个命令启动看板API服务器和MCP服务器：

# Install dependencies first
npm install

# Build TypeScript
npm run build

# Start both API and MCP server (automatic cleanup)
npm run start:combined

此脚本：

  1. 在后台启动看板API服务器
  2. 等待它准备就绪（检查端口3000）
  3. 以stdio模式启动MCP服务器
  4. MCP退出时自动停止API服务器

手动启动

您也可以单独启动服务器：

# Terminal 1: Start Kanban API server
cd ../life-system-kanban
npm run server

# Terminal 2: Start MCP server
cd ../mcp-server
npm start

发展

# Install dependencies
npm install

# Run in development mode (requires API server running separately)
npm run dev

# Build TypeScript
npm run build

测试

# Run tests once (for CI/CD)
npm run test:run

# Run tests in watch mode
npm test

# Run with coverage
npm test -- --coverage

测试状态： ✅ 在~450ms内通过42次测试

看 测试_用户.md 获取详细的测试文档。

项目结构

mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   ├── test/
│   │   └── mocks.ts          # Mock utilities for testing
│   ├── validation.test.ts     # Validation tests (20 tests)
│   └── tools.test.ts          # Tool tests (22 tests)
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── vitest.config.ts           # Test configuration
├── README.md                  # This file
└── TEST_GUIDE.md              # Comprehensive testing guide

MCP工具

车道管理（4个工具）

  • list_lanes -获取所有车道
  • create_lane -创建新车道
  • update_lane -更新车道属性
  • delete_lane -删除一个通道（级联到卡）

卡片管理（5个工具）

  • list_cards -获取所有卡片（可选择按通道过滤）
  • create_card -创建新卡
  • update_card -更新卡属性
  • delete_card -删除卡片
  • move_card -将卡片移动到不同的车道/位置

董事会操作（2个工具）

  • get_board -使用嵌套卡获取完整的板状态
  • get_board_summary -获取包含计数的文本摘要

依赖项

运行时

  • @modelcontextprotocol/sdk -MCP协议实现
  • typescript -TypeScript编译器
  • tsx -TypeScript执行

发展

  • vitest -快速测试框架
  • @types/node -Node.js类型定义

配置

API连接

服务器连接到Kanban API的位置为：

http://localhost:3000/api

看板API必须运行，MCP服务器才能运行。使用以下任一方法：

  • 联合启动： npm run start:combined （自动处理API服务器）
  • 手动启动： cd ../life-system-kanban && npm run server

MCP注册

要将此服务器与Claude Code一起使用，请在中注册 ~/.claude/.mcp.json:

选项1：联合启动（推荐）

{
  "mcpServers": {
    "kanban": {
      "command": "node",
      "args": ["/agent/data/files/mcp-server/start.js"],
      "cwd": "/agent/data/files/mcp-server"
    }
  }
}

选项2：手动（要求API服务器已在运行）

{
  "mcpServers": {
    "kanban": {
      "command": "node",
      "args": ["/agent/data/files/mcp-server/dist/index.js"]
    }
  }
}

特性

输入验证

所有工具在进行API调用之前验证输入：

  • 所需现场人员
  • 类型检查（字符串、数字、整数）
  • 格式验证（十六进制颜色：#RRGGBB）
  • 范围检查（非负整数）

错误处理

全面的错误处理和有用的消息：

  • 缺少必填字段
  • 数据类型无效
  • API连接失败（有指导）
  • HTTP错误响应（404、500等）

测试

基于模拟的测试消除了外部依赖：

  • 所有使用Vitest模拟的HTTP调用
  • 42项测试，涵盖验证和所有工具
  • 快速执行（~450ms）
  • CI/CD就绪

开发状态

状态： 测试基础设施完成✅

完整的：

  1. ✅ 安装依赖项
  2. ✅ 运行看板测试套件
  3. ✅ 初始化MCP服务器项目
  4. ✅ 实施卡片管理工具
  5. ✅ 实施董事会级操作
  6. ✅ 添加错误处理和验证
  7. ✅ 设置测试基础设施
  8. ✅ 创建组合启动脚本（start.sh、start.js）

下一步：

  1. 在中注册MCP服务器 ~/.claude/.mcp.json
  2. 测试MCP服务器与看板API的集成
  3. 更新内存和CLAUDE.md以防止清理

文档

  • 测试_用户.md -全面的测试指南
  • 验证.md -输入验证文档
  • 项目状态： /agent/data/files/plans/7f9fc9b8-ccfe-4463-9bff-05b15448ca86/status.md

建筑

MCP服务器使用stdio传输与Claude Code通信：

  1. Claude Code将服务器作为子进程启动
  2. 使用JSON-RPC通过stdin/stdout进行通信
  3. 服务器公开了11个包装看板REST API的工具
  4. 每个工具验证输入并对API进行HTTP调用
  5. 结果以JSON或错误消息的形式返回

许可证

Jane个人助理系统的一部分。

相关 MCP