Taiga MCP Bridge

泰加MCP大桥

\

概述

Taiga MCP Bridge是一个强大的集成层，用于连接 泰加 采用模型上下文协议（MCP）的项目管理平台，使人工智能工具和工作流能够与Taiga的资源无缝交互。

该桥为AI代理提供了一套全面的工具和资源，以：

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

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

特性

全面的资源支持

该桥支持以下具有完整CRUD操作的Taiga资源：

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

安全与配置

• 安全凭据：具有凭据保护的环境变量身份验证-密码永远不会出现在日志或错误消息中
• 自动身份验证：配置 TAIGA_USERNAME 和 TAIGA_PASSWORD 无需手动登录即可无缝启动的环境变量
• 输入验证：基于Allowlist的参数验证可防止意外数据到达Taiga API

响应过滤

所有工具均支持 verbosity 控制响应大小的参数，减少AI上下文的使用：

例子：

# Get minimal response for efficient context usage
stories = client.call_tool("list_user_stories", {
    "project_id": 123,
    "verbosity": "minimal"
})
# Returns: [{"id": 1, "ref": 42, "subject": "...", "status": 1, "project": 123}, ...]

安装

此项目使用 紫外线 用于快速、可靠的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_USERNAME=your_username
TAIGA_PASSWORD=your_password
TAIGA_TRANSPORT=stdio
LOG_LEVEL=INFO

安全说明：凭据受到保护，永远不会出现在日志、错误消息或堆栈跟踪中。当 TAIGA_USERNAME 和 TAIGA_PASSWORD 如果已配置，服务器将在启动时自动进行身份验证，无需手动登录。

用法

使用stdio模式

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

推荐：通过shell配置文件中的环境变量设置凭据，而不是在配置文件中设置凭据，以避免以明文形式公开它们。

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "
",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "",                
                "TAIGA_API_URL": "",
                "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. 标准输入/输出 -基于终端的客户端的默认模式
2. SSE（服务器发送事件） -基于Web的传输，具有服务器推送功能

您可以通过多种方式设置传输模式：

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

身份验证流程

自动身份验证（推荐）

如果 TAIGA_USERNAME 和 TAIGA_PASSWORD 如果设置了环境变量，服务器将在启动时自动进行身份验证。你可以省略 session_id 从工具调用中使用默认会话：

# No login needed - uses auto-authenticated default session
projects = client.call_tool("list_projects", {})
stories = client.call_tool("list_user_stories", {"project_id": 123})
new_story = client.call_tool("create_user_story", {
    "project_id": 123,
    "subject": "New feature request"
})

手动会话管理

对于需要多个会话或显式控制的场景，请使用基于会话的模型：

1. 登录：使用身份验证 login 工具：

   session = client.call_tool("login", {
       "username": "your_taiga_username",
       "password": "your_taiga_password",
       "host": "https://api.taiga.io" # Optional
   })
   # Save the session_id from the response
   session_id = session["session_id"]

1. 使用工具和资源：包括 session_id 在每个API调用中：

   # For resources, include session_id in the URI
   projects = client.get_resource(f"taiga://projects?session_id={session_id}")

   # For project-specific resources
   epics = client.get_resource(f"taiga://projects/123/epics?session_id={session_id}")

   # For tools, include session_id as a parameter
   new_project = client.call_tool("create_project", {
       "session_id": session_id,
       "name": "New Project",
       "description": "Description"
   })

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

   status = client.call_tool("session_status", {"session_id": session_id})
   # Returns information about session validity and remaining time

1. 退出登录：完成后，您可以注销以终止会话：

   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 wrapper
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── test_server.py     # Unit tests
│   └── test_integration.py # 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 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"
}

计划的功能

计划在未来的版本中提供以下功能：

• 会话过期和自动清理
• API调用的速率限制
• 具有指数回退的重试机制
• 连接池

贡献

欢迎投稿！请随时提交拉取请求。

1. 克隆该仓库
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. 打开拉取请求

许可证

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

致谢

• 泰加 因为他们优秀的项目管理平台
• 模型上下文协议（MCP） 用于标准化的人工智能通信框架
• 所有帮助塑造这个项目的贡献者