Taiga MCP 桥接器

概述

Taiga MCP 桥接器是一个强大的集成层，将 Taiga 项目管理平台与模型上下文协议 (MCP) 相连接，使 AI 工具和工作流能够无缝地与 Taiga 资源交互。

该桥接器为 AI 代理提供了一套完整的工具和资源，用于：

• 在 Taiga 中创建和管理项目、史诗、用户故事、任务和问题
• 跟踪冲刺和里程碑
• 分配和更新工作项
• 查询项目工件的详细信息
• 管理项目成员和权限

通过使用 MCP 标准，该桥接器使 AI 系统能够保持对项目状态的上下文感知，并以编程方式执行复杂的项目管理任务。

功能

全面的资源支持

桥接器支持以下 Taiga 资源的完整 CRUD 操作：

• 项目：创建、更新和管理项目设置及元数据
• 史诗：管理跨越多个冲刺的大型功能
• 用户故事：处理详细的需求和验收标准
• 任务：跟踪用户故事中的较小工作单元
• 问题：管理错误、问题和增强请求
• 冲刺（里程碑）：计划和跟踪时间箱间隔内的工作

安装

本项目使用 uv 进行快速、可靠的 Python 包管理。

先决条件

• Python 3.10 或更高版本
• uv 包管理器

基本安装

# 克隆仓库
git clone https://github.com/your-org/pyTaigaMCP.git
cd pyTaigaMCP

# 安装依赖
./install.sh

开发安装

用于开发（包括测试和代码质量工具）：

./install.sh --dev

手动安装

如果更喜欢手动安装：

# 仅生产依赖
uv pip install -e .

# 包含开发依赖
uv pip install -e ".[dev]"

配置

桥接器可通过环境变量或 .env 文件进行配置：

在项目根目录创建 .env 文件以设置这些值：

TAIGA_API_URL=https://api.taiga.io/api/v1/
TAIGA_TRANSPORT=sse
LOG_LEVEL=DEBUG

使用

使用 stdio 模式

将以下 json 粘贴到 Claude App 或 Cursor 的 mcp 设置部分：

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "<本地 pyTaigaMCP 文件夹路径>",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "<stdio|sse>",                
                "TAIGA_API_URL": "<Taiga API 地址 (例如 http://localhost:9000)",
                "TAIGA_USERNAME": "<taiga 用户名>",
                "TAIGA_PASSWORD": "<taiga 密码>"
            }
        }
}

运行桥接器

启动 MCP 服务器：

# 默认 stdio 传输
./run.sh

# 使用 SSE 传输
./run.sh --sse

或手动：

# 使用 stdio 传输（默认）
uv run python src/server.py

# 使用 SSE 传输
uv run python src/server.py --sse

传输模式

服务器支持两种传输模式：

1. stdio（标准输入/输出） - 基于终端客户端的默认模式
2. SSE（服务器发送事件） - 具有服务器推送功能的基于 Web 的传输

可以通过以下方式设置传输模式：

• 使用 run.sh 或 server.py 的 --sse 标志（默认为 stdio）
• 设置 TAIGA_TRANSPORT 环境变量
• 在 .env 文件中添加 TAIGA_TRANSPORT=sse

认证流程

该 MCP 桥接器使用基于会话的认证模型：

1. 登录：客户端必须首先使用 login 工具进行认证：

   python 复制代码

   session = client.call_tool("login", {
       "username": "your_taiga_username",
       "password": "your_taiga_password",
       "host": "https://api.taiga.io" # 可选
   })
   # 从响应中保存 session_id
   session_id = session["session_id"]

2. 使用工具和资源：在每次 API 调用中包含 session_id：

   python 复制代码

   # 对于资源，在 URI 中包含 session_id
   projects = client.get_resource(f"taiga://projects?session_id={session_id}")
   
   # 对于项目特定资源
   epics = client.get_resource(f"taiga://projects/123/epics?session_id={session_id}")
   
   # 对于工具，将 session_id 作为参数包含
   new_project = client.call_tool("create_project", {
       "session_id": session_id,
       "name": "新项目",
       "description": "描述"
   })

3. 检查会话状态：可以检查会话是否仍然有效：

   python 复制代码

   status = client.call_tool("session_status", {"session_id": session_id})
   # 返回有关会话有效性和剩余时间的信息

4. 注销：完成后，可以注销以终止会话：

   python 复制代码

   client.call_tool("logout", {"session_id": session_id})

示例：完整的项目创建工作流

以下是创建包含史诗和用户故事的项目的完整示例：

from mcp.client import Client

# 初始化 MCP 客户端
client = Client()

# 认证并获取会话 ID
auth_result = client.call_tool("login", {
    "username": "admin",
    "password": "password123",
    "host": "https://taiga.mycompany.com"
})
session_id = auth_result["session_id"]

# 创建新项目
project = client.call_tool("create_project", {
    "session_id": session_id,
    "name": "我的新项目",
    "description": "通过 MCP 创建的测试项目"
})
project_id = project["id"]

# 创建史诗
epic = client.call_tool("create_epic", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "用户认证",
    "description": "实现用户认证功能"
})
epic_id = epic["id"]

# 在史诗中创建用户故事
story = client.call_tool("create_user_story", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "用户登录",
    "description": "作为用户，我希望能够使用我的凭据登录",
    "epic_id": epic_id
})

# 完成后注销
client.call_tool("logout", {"session_id": session_id})

开发

项目结构

pyTaigaMCP/
├── src/
│   ├── server.py          # 包含工具的 MCP 服务器实现
│   ├── taiga_client.py    # 包含所有 CRUD 操作的 Taiga API 客户端
│   ├── tools.py           # MCP 工具定义
│   └── config.py          # 使用 Pydantic 的配置设置
├── tests/
│   ├── conftest.py        # 共享的 pytest fixtures
│   ├── unit/              # 单元测试
│   └── integration/       # 集成测试
├── pyproject.toml         # 项目配置和依赖
├── install.sh             # 安装脚本
├── run.sh                 # 服务器执行脚本
└── README.md              # 项目文档

测试

使用 pytest 运行测试：

# 运行所有测试
pytest

# 仅运行单元测试
pytest tests/unit/

# 仅运行集成测试
pytest tests/integration/

# 运行带有特定标记的测试
pytest -m "auth"  # 认证测试
pytest -m "core"  # 核心功能测试

# 运行带有覆盖率报告的测试
pytest --cov=src

调试和检查

使用包含的检查工具进行调试：

# 默认 stdio 传输
./inspect.sh

# 使用 SSE 传输
./inspect.sh --sse

# 开发模式
./inspect.sh --dev

错误处理

所有 API 操作均返回标准化的错误响应，格式如下：

{
  "status": "error",
  "error_type": "ExceptionClassName",
  "message": "详细的错误消息"
}

性能考虑

桥接器实现了多项性能优化：

1. 连接池：重用 HTTP 连接以提高性能
2. 速率限制：防止 Taiga API 过载
3. 重试机制：使用指数退避自动重试失败的请求
4. 会话清理：定期清理过期会话以释放资源

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 安装开发依赖（./install.sh --dev）
4. 进行更改
5. 运行测试（pytest）
6. 提交更改（git commit -m '添加一些很棒的功能'）
7. 推送到分支（git push origin feature/amazing-feature）
8. 打开 Pull Request

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

致谢

• Taiga 提供优秀的项目管理平台
• 模型上下文协议 (MCP) 提供标准化的 AI 通信框架
• 所有帮助塑造本项目的贡献者