Backlog Manager MCP Server

一个用于AI助手的任务跟踪和待办事项管理的MCP服务器（黑客项目）

<p align="center"> <img src="https://img.shields.io/badge/状态-Beta黄色" alt="状态: Beta"> <img src="https://img.shields.io/badge/Python-3.12%2B绿色" alt="Python: 3.12+"> </p>

目录

• 概述
• 特性
• 前置条件
• 安装
• 配置
• 运行服务器
• MCP工具
• 与MCP客户端集成
• 使用示例
• 故障排除
• 贡献
• 许可

概述

Backlog Manager 是一个基于文件的MCP（机器可消费编程）服务器，用于问题和任务管理。它提供了工具让AI代理和其他客户端创建问题，向问题中添加任务，并追踪任务状态。问题代表高层次的功能请求或错误，而任务则代表解决这些问题的具体工作项。

使用Anthropic的MCP协议构建，支持SSE和stdio传输，以灵活地与像Claude这样的AI助手或其他兼容MCP的客户端进行集成。

特性

• 问题管理：创建、列出、选择并追踪带有描述的问题
• 任务追踪：向问题中添加带有标题、描述和状态追踪的任务
• 状态流程：通过新建、进行中和完成状态来追踪任务进度
• 基于文件的存储：便携的JSON存储格式，便于备份和版本控制
• 灵活的传输：支持SSE（HTTP）和stdio通信
• Docker支持：在容器中运行，便于部署和隔离

前置条件

• Python：3.12或更高版本
• 包管理器：uv（推荐）或pip
• Docker：（可选）用于容器化部署
• MCP客户端：Claude Code，Windsurf，或其他兼容MCP的客户端

安装

使用uv（推荐）

# 克隆仓库
git clone https://github.com/username/backlog-manager-mcp.git
cd backlog-manager-mcp

# 安装依赖
uv pip install -e .

# 验证安装
uv run backlog-manager  # 这应该启动服务器

使用Docker

# 构建Docker镜像
docker build -t backlog/manager --build-arg PORT=8050 .

# 运行容器
docker run -p 8050:8050 backlog/manager

# 验证容器是否运行
docker ps | grep backlog/manager

配置

使用环境变量在.env文件中配置服务器行为：

# 从示例创建环境文件
cp .env.example .env

示例.env文件内容：

# 传输模式：'sse' 或 'stdio'
TRANSPORT=sse

# 服务器配置（对于SSE传输）
HOST=0.0.0.0
PORT=8050

# 数据存储
TASKS_FILE=tasks.json

变量	描述	默认值	必需
TRANSPORT	传输协议（sse 或 stdio）	sse	否
HOST	使用SSE传输时绑定的主机地址	0.0.0.0	否
PORT	使用SSE传输时监听的端口	8050	否
TASKS_FILE	任务存储文件的路径	tasks.json	否

运行服务器

启动服务器（SSE模式）

# 使用CLI命令
uv run backlog-manager

# 或直接使用Python
uv run src/backlog_manager/main.py

你应该看到类似以下的输出：

INFO:     已启动服务器进程 [12345]
INFO:     正在等待应用程序启动。
INFO:     应用程序启动完成。
INFO:     Uvicorn正在运行于 http://0.0.0.0:8050 （按CTRL+C退出）

注意：由于该服务器设计为MCP服务器而非传统的CLI应用，因此不支持--help标志。

使用stdio模式

当使用stdio模式时，无需单独启动服务器——只要MCP客户端正确配置（参见与MCP客户端集成），它会自动启动服务器。

MCP工具

Backlog Manager 通过MCP暴露了以下工具：

问题管理

工具	描述	参数
create_issue	创建新问题	name (字符串)，description (字符串，可选)，status (字符串，可选)
list_issues	显示所有可用问题	无
select_issue	设置当前活动问题	name (字符串)
initialize_issue	创建或重置问题	name (字符串)，description (字符串，可选)，status (字符串，可选)
update_issue_status	更新问题状态	name (字符串)，status (字符串)

任务管理

工具	描述	参数
add_task	向当前活动问题添加任务	title (字符串)，description (字符串，可选)
list_tasks	列出当前活动问题中的任务	status (字符串，可选)
update_task_status	更新任务状态	task_id (字符串)，status (字符串)

状态值

任务和问题可以具有以下状态之一：

• New（新任务/问题的默认状态）
• InWork（进行中）
• Done（已完成）

与MCP客户端集成

SSE配置

一旦你使用SSE传输运行了服务器，可以通过以下配置连接到它：

{
  "mcpServers": {
    "backlog-manager": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}

Windsurf配置：

{
  "mcpServers": {
    "backlog-manager": {
      "transport": "sse",
      "serverUrl": "http://localhost:8050/sse"
    }
  }
}

n8n配置：

使用host.docker.internal而不是localhost来从n8n容器访问主机机器：

http://host.docker.internal:8050/sse

Python与stdio配置

{
  "mcpServers": {
    "backlog-manager": {
      "command": "python",
      "args": ["path/to/backlog-manager/src/backlog_manager/main.py"],
      "env": {
        "TRANSPORT": "stdio",
        "TASKS_FILE": "tasks.json"
      }
    }
  }
}

Docker与stdio配置

{
  "mcpServers": {
    "backlog-manager": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "TRANSPORT=stdio", "backlog/manager"],
      "env": {
        "TRANSPORT": "stdio"
      }
    }
  }
}

示例

Backlog Manager 设计为与AI助手无缝协作，帮助你组织项目工作。最强大的用例是让AI阅读规范并自动创建结构化的待办事项。

只需询问你的AI助手：

读取规范并为未完成的功能创建待办事项。

AI助手将：

1. 阅读并分析规范文档
2. 识别关键功能和组件
3. 为主功能区域创建问题
4. 将每个问题分解成具体任务
5. 将一切组织成结构化的待办事项