Taiga MCP Bridge

Taiga MCP Bridge

talhaorak/pytaiga-mcp 的社区分支，新增了功能、CI/CD，并持续维护。

概述

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

该 Bridge 为 AI Agent 提供了一套全面的工具和资源，用于：

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

借助 MCP 标准，该 Bridge 让 AI 系统能够了解项目状态，并以编程方式执行复杂的项目管理任务。

功能

全面的资源支持

该 Bridge 支持以下 Taiga 资源的完整 CRUD 操作：

• 项目：创建、更新和管理项目设置及元数据
• 史诗：管理跨越多个冲刺的大型功能
• 用户故事：处理详细需求和验收标准
• 任务：跟踪用户故事中的较小工作单元
• 问题：管理 Bug、疑问和改进请求
• 冲刺（里程碑）：规划并跟踪有时间限制的工作周期

安全与配置

• 安全凭据：通过环境变量进行身份验证并保护凭据——密码绝不会出现在日志或错误消息中
• 自动身份验证：配置 TAIGA_USERNAME 和 TAIGA_PASSWORD 环境变量，即可无须手动登录而顺利启动
• 输入验证：基于允许列表的参数验证可防止意外数据传入 Taiga API

响应筛选

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

级别	描述	使用场景
minimal	仅包含核心字段（id、ref、subject、status、project）	列出大量项目
standard	包含用于更新的版本号等常用字段（默认）	日常操作
full	完整的 API 响应	调试、查看完整详情

示例：

# 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}, ...]

安装

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

前置条件

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

基本安装

# Clone the repository
git clone https://github.com/TETRA-2023/pytaiga-mcp.git
cd pytaiga-mcp

# Install dependencies
./install.sh

开发环境安装

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

./install.sh --dev

手动安装

如果你希望手动安装：

# Production dependencies only
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"

Docker

从 GHCR 拉取预构建镜像：

docker pull ghcr.io/tetra-2023/pytaiga-mcp:latest

或者在本地构建：

docker build -t pytaiga-mcp .

使用环境变量运行：

docker run -i --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  ghcr.io/tetra-2023/pytaiga-mcp:latest

要使用 SSE 传输而不是 stdio，请追加 --sse：

docker run --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -p 8000:8000 \
  ghcr.io/tetra-2023/pytaiga-mcp:latest --sse

stdio 传输的 MCP 客户端配置示例（.mcp.json）：

{
  "mcpServers": {
    "taigaApi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TAIGA_API_URL",
        "-e", "TAIGA_USERNAME",
        "-e", "TAIGA_PASSWORD",
        "ghcr.io/tetra-2023/pytaiga-mcp:latest"
      ]
    }
  }
}

注意：对于 stdio 传输，请使用 -i（交互模式），不要使用 -t（伪 TTY）。-e VAR 形式（不含 =value）会从主机环境转发变量。

配置

可以通过环境变量或 .env 文件配置此桥接程序：

环境变量	说明	默认值
TAIGA_API_URL	Taiga API 的基础 URL	http://localhost:9000
TAIGA_USERNAME	用于自动身份验证的 Taiga 用户名	（无）
TAIGA_PASSWORD	用于自动身份验证的 Taiga 密码	（无）
TAIGA_TRANSPORT	传输模式（stdio 或 sse）	stdio
LOG_LEVEL	日志级别	INFO

在项目根目录中创建 .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",
                "<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 传输方式

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

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

身份验证流程

自动身份验证（推荐）

如果设置了 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"]
   

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

   # 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"
   })
   

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

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

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})

开发

项目结构

pytaiga-mcp/
├── 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
├── .github/workflows/
│   └── ci.yml             # CI pipeline (test, lint, Docker, release)
├── .pre-commit-config.yaml # Pre-commit hooks (ruff, pytest)
├── Dockerfile             # Container image definition
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

测试

每次提交时都会自动运行 pre-commit 钩子（ruff lint、ruff format、单元测试）。如需手动运行：

# Run pre-commit hooks on all files
uv run pre-commit run --all-files

# Run tests directly
uv run pytest tests/test_server.py -v --tb=short

# Run with coverage reporting
uv run 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 调用速率限制
• 带指数退避的重试机制
• 连接池

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 安装开发依赖项（./install.sh --dev）
4. 设置 pre-commit 钩子（uv run pre-commit install）
5. 修改代码
6. 提交更改 — pre-commit 钩子将自动运行 lint 和测试
7. 推送到分支（git push origin feature/amazing-feature）
8. 创建 Pull Request

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

致谢

• 感谢 Taiga 提供出色的项目管理平台
• 感谢 Model Context Protocol (MCP) 提供标准化的 AI 通信框架
• 感谢所有帮助完善本项目的贡献者