Taiga MCP 桥接器

<p align="center"> <picture> <img src="https://taiga.io/media/images/favicon.width-44.png"> </picture> </p>

概述

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 文件配置桥接器：

环境变量	描述	默认值
TAIGA_API_URL	Taiga API 的基本 URL	http://localhost:9000
SESSION_EXPIRY	会话过期时间（秒）	28800 (8 小时)
TAIGA_TRANSPORT	传输模式 (stdio 或 sse)	stdio
REQUEST_TIMEOUT	API 请求超时时间（秒）	30
MAX_CONNECTIONS	HTTP 连接的最大数量	10
MAX_KEEPALIVE_CONNECTIONS	最大保持活动连接数	5
RATE_LIMIT_REQUESTS	每分钟最大请求数	100
LOG_LEVEL	日志记录级别	INFO
LOG_FILE	日志文件路径	taiga_mcp.log

在项目根目录中创建一个 .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 Url (例如：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 环境变量
• 将 TAIGA_TRANSPORT=sse 添加到您的 .env 文件

身份验证流程

此 MCP 桥接器使用基于会话的身份验证模型：

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

   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：

   # 对于资源，在 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": "New Project",
       "description": "Description"
   })
   

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

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

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

   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": "My New Project",
    "description": "A test project created via MCP"
})
project_id = project["id"]

# 创建一个史诗
epic = client.call_tool("create_epic", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Authentication",
    "description": "Implement user authentication features"
})
epic_id = epic["id"]

# 在史诗中创建一个用户故事
story = client.call_tool("create_user_story", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Login",
    "description": "As a user, I want to log in with my credentials",
    "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 'Add some amazing feature')
7. 将分支推送到远程仓库 (git push origin feature/amazing-feature)
8. 打开一个 Pull Request

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Taiga 感谢他们出色的项目管理平台
• 模型上下文协议 (MCP) 感谢标准化的 AI 通信框架
• 感谢所有帮助塑造此项目的贡献者