Taiga MCP 桥接器

概述

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

此桥接器为 AI 代理提供了全面的工具和资源，以实现以下功能：

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

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

功能

全面的资源支持

该桥接器支持以下 Taiga 资源，并提供完整的 CRUD 操作：

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

安装

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

前提条件

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

基本安装

# Clone the repository
git clone https://github.com/your-org/pyTaigaMCP.git
cd pyTaigaMCP

# Install dependencies
./install.sh

开发安装

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

./install.sh --dev

手动安装

如果您更喜欢手动安装：

# Production dependencies only
uv pip install -e .

# With development dependencies
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 应用程序或 Cursor 的 MCP 设置部分：

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "<path to local pyTaigaMCP folder>",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "<stdio|sse>",                
                "TAIGA_API_URL": "<Taiga API Url (ex: http://localhost:9000)",
                "TAIGA_USERNAME": "<taiga username>",
                "TAIGA_PASSWORD": "<taiga password>"
            }
        }
}

运行桥接器

启动 MCP 服务器：

# Default stdio transport
./run.sh

# For SSE transport
./run.sh --sse

或者手动运行：

# For stdio transport (default)
uv run python src/server.py

# For SSE transport
uv run python src/server.py --sse

传输模式

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

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

您可以使用以下几种方式设置传输模式：

• 使用 --sse 标志与 run.sh 或 server.py（默认为 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

# Initialize MCP client
client = Client()

# Authenticate and get session ID
auth_result = client.call_tool("login", {
    "username": "admin",
    "password": "password123",
    "host": "https://taiga.mycompany.com"
})
session_id = auth_result["session_id"]

# Create a new project
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"]

# Create an epic
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"]

# Create a user story in the epic
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
})

# Logout when done
client.call_tool("logout", {"session_id": session_id})

开发

项目结构

pyTaigaMCP/
├── src/
│   ├── server.py          # MCP server implementation with tools
│   ├── taiga_client.py    # Taiga API client with all CRUD operations
│   ├── tools.py           # MCP tools definitions
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── conftest.py        # Shared pytest fixtures
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

测试

使用pytest运行测试：

# Run all tests
pytest

# Run only unit tests
pytest tests/unit/

# Run only integration tests
pytest tests/integration/

# Run tests with specific markers
pytest -m "auth"  # Authentication tests
pytest -m "core"  # Core functionality tests

# Run tests with coverage reporting
pytest --cov=src

调试和检查

使用附带的检查器工具进行调试：

# Default stdio transport
./inspect.sh

# For SSE transport
./inspect.sh --sse

# For development mode
./inspect.sh --dev

错误处理

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

{
  "status": "error",
  "error_type": "ExceptionClassName",
  "message": "Detailed error 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 提供了出色的项目管理平台
• Model Context Protocol (MCP) 提供了标准化的AI通信框架
• 所有帮助塑造此项目的贡献者们