Taiga MCP 桥

概述

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

这座桥梁为人工智能代理提供了一套全面的工具和资源，可以：

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

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

特征

全面的资源支持

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

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

安装

该项目使用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文件配置桥接器：

环境变量	描述	默认
`TAIGA_API_URL`	Taiga API 的基本 URL	http://localhost:9000
`SESSION_EXPIRY`	会话过期时间（以秒为单位）	28800（8小时）
`TAIGA_TRANSPORT`	传输模式（stdio 或 sse）	标准输入输出
`REQUEST_TIMEOUT`	API 请求超时（秒）	三十
`MAX_CONNECTIONS`	最大 HTTP 连接数	10
`MAX_KEEPALIVE_CONNECTIONS`	最大保持连接数	5
`RATE_LIMIT_REQUESTS`	每分钟最大请求数	100
`LOG_LEVEL`	日志级别	信息
`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",
                "<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

交通方式

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

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

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

将--sse标志与 run.sh 或 server.py 一起使用（默认为 stdio）
设置TAIGA_TRANSPORT环境变量
将TAIGA_TRANSPORT=sse添加到您的.env文件

身份验证流程

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

登录：客户端必须首先使用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"]
使用工具和资源：在每个 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" })
检查会话状态：您可以检查会话是否仍然有效：
status = client.call_tool("session_status", {"session_id": session_id}) # Returns information about session validity and remaining time
注销：完成后，您可以注销以终止会话：
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"
}

性能考虑

该桥实现了几项性能优化：

连接池：重用 HTTP 连接以获得更好的性能
速率限制：防止 Taiga API 过载
重试机制：使用指数退避算法自动重试失败的请求
会话清理：定期清理过期会话以释放资源

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
安装开发依赖项（ ./install.sh --dev ）
进行更改
运行测试（ pytest ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

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

致谢

Taiga提供出色的项目管理平台
用于标准化 AI 通信框架的模型上下文协议 (MCP)
所有参与该项目的贡献者

Taiga MCP Bridge

Integrations