Taiga MCP Server

泰加MCP服务器

适用于Taiga项目管理的生产就绪型模型上下文协议（MCP）服务器

  

入门指南 • 特点/特性 • 工具 • 建筑 • 做出贡献

______________________________________________________________________

📋 概述

Taiga MCP服务器实现了大型语言模型（LLMs）与（其他系统/服务）之间的无缝集成 泰加（或泰加林） 通过模型上下文协议实现的项目管理平台。该平台采用Python的异步/等待（async/await）模式和类型安全的Pydantic模型构建，为AI驱动的项目管理自动化提供了稳健且可直接投入生产的解决方案。

为什么选择Taiga MCP？

• 🤖 自然语言接口使用对话命令与Taiga进行交互
• 🔄 优先异步基于现代的async/await技术，实现高性能
• 🛡️ 类型安全进行全面的Pydantic验证以确保可靠性
• 🎯 准备就绪，可投入生产全面的错误处理和日志记录
• 🔌 可扩展简洁的架构，便于轻松添加功能
• 📦 零配置开箱即用，兼容Claude Desktop、Cursor、Windsurf

______________________________________________________________________

✨ 特点/功能

核心能力

✅ 任务管理 在故事中创建和组织任务 👥 团队协作 | 查看成员并分配工作 | | 标签： 丰富的元数据 | 标签、故事点、截止日期、自定义字段 | | 🔍（放大镜图标，可翻译为“放大镜”或根据上下文保持为符号） 灵活查询 | 支持ID、别名和参考编号 (#42) |

技术特性

• 异步架构非阻塞I/O以实现最佳性能
• 智能缓存自动刷新的令牌管理
• 智能分页自动获取全部或逐页获取
• 乐观锁基于版本的更新可避免冲突
• 基于角色的积分自动检测与处理
• 灵活标识符使用ID、别名或#ref编号互换使用

______________________________________________________________________

🚀 快速入门

先决条件

• python3.10或更高版本
• 泰加账户taiga.io 或自托管实例
• MCP 客户端Claude Desktop、Cursor、Windsurf 或任何MCP兼容客户端

安装

# Clone the repository
git clone https://github.com/yourusername/taiga-mcp.git
cd taiga-mcp

# Create virtual environment (or use conda)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Configure credentials
cp .env.example .env
nano .env  # Add your Taiga credentials

配置

创建 .env 文件：

TAIGA_API_URL=https://api.taiga.io/api/v1
TAIGA_USERNAME=your_username
TAIGA_PASSWORD=your_password
DEBUG=false

见 RUN.md（文件名，可译为“运行说明.md”或保持原样，根据上下文决定是否需要具体翻译文件名） 以下是Claude Desktop和Claude Code的详细设置指南。

______________________________________________________________________

🛠️ 可用工具

服务器通过MCP协议提供了10种工具：

认证

项目管理

用户故事管理

任务管理

_\* |_

______________________________________________________________________

\* = 可选参数

💬 示例用法

"List all my Taiga projects"

"Show me details about project 'mobile-app'"

"Create a user story in backend-api titled 'Implement OAuth2 authentication'
with description 'Add JWT-based OAuth2 flow for API endpoints'"

"List all user stories in the mobile-app project"

"Update user story #42 - set status to 'In Progress' and assign to john"

"Show me all tasks for user story #42"

"Create a task in story #42 titled 'Write unit tests for auth module'"

______________________________________________________________________

一旦使用您的LLM客户端进行配置后，即可使用自然语言：

🏗️ 建筑学

技术栈 | 组件 | 技术 | 目的 | |-----------|-----------|---------| | 协议；规程 | MCP 1.0 | 大语言模型工具通信 | | 语言 | Python 3.10+ | 核心实现 | | HTTP 客户端 | httpx（注：httpx通常是一个用于HTTP请求的工具或库的名称，在中文中没有直接对应的翻译，因此保持原样。） 异步Taiga API调用 | 验证 | Pydantic v2 | 类型安全的数据模型 | | 配置 | pydantic-settings（可译为“Pydantic设置”或保持原样，根据上下文决定是否需要具体翻译） | 环境管理 | | 测试 | pytest + pytest-asyncio

| 测试框架 |

taiga-mcp/
├── app/                          # Main application package
│   ├── core/                     # Core functionality
│   │   ├── auth.py              # Authentication & token management
│   │   ├── client.py            # Async HTTP client wrapper
│   │   └── exceptions.py        # Custom exception hierarchy
│   ├── models/                   # Pydantic data models
│   │   ├── project.py           # Project & member models
│   │   ├── userstory.py         # User story models
│   │   ├── task.py              # Task models
│   │   ├── user.py              # User models
│   │   └── status.py            # Status models
│   ├── services/                 # Business logic layer
│   │   ├── project_service.py   # Project operations
│   │   ├── userstory_service.py # User story operations
│   │   ├── task_service.py      # Task operations
│   │   └── user_service.py      # User operations
│   ├── config.py                 # Settings management
│   └── server.py                 # MCP server & tool definitions
├── tests/                        # Test suite
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── pyproject.toml               # Project metadata & dependencies
├── README.md                    # This file
├── RUN.md                       # Setup & usage guide
└── .env.example                 # Example environment config

项目结构

设计模式 1.

全程使用 Async/Await async/await 所有的输入/输出操作都使用Python的

async with TaigaClient() as client:
    projects = await project_service.list_projects()

对于非阻塞执行： 2.

服务层模式

class ProjectService:
    async def list_projects(self) -> list[Project]:
        data = await self.client.get("/projects")
        return [Project(**proj) for proj in data]

业务逻辑封装在服务类中： 3.

Pydantic 验证

class UserStory(BaseModel):
    id: int
    subject: str
    tags: list[str] = Field(default_factory=list)

    @field_validator("tags", mode="before")
    @classmethod
    def normalize_tags(cls, v: Any) -> list[str]:
        # Handle both ['tag'] and [['tag', None]] formats
        ...

所有数据均使用 Pydantic 模型进行验证： 4.

错误处理

try:
    await client.get("/projects/123")
except ResourceNotFoundError as e:
    logger.error(f"Project not found: {e.identifier}")
except TaigaAPIError as e:
    logger.error(f"API error: {e.status_code}")

______________________________________________________________________

自定义异常层次结构以实现精确的错误处理：

🔧 开发

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=app --cov-report=html

# Format code
black app/ tests/

# Lint code
ruff check app/ tests/

# Type check
mypy app/

设置开发环境

# All tests
pytest

# Specific test file
pytest tests/unit/test_auth.py -v

# Integration tests (requires Taiga credentials)
pytest tests/integration/ -v

# With coverage report
pytest --cov=app --cov-report=term-missing

运行测试

代码质量工具 | 工具 | 用途 | 命令 | |------|---------|---------| | 黑色 black app/ tests/ | 代码格式化 | | | “Ruff”在中文中可以翻译为“粗糙”或“粗犷”，具体取决于上下文和语境。如果是指外观或质地上的粗糙，可以翻译为“粗糙”；如果是指性格或风格上的粗犷，可以翻译为“粗犷” ruff check app/ tests/ | 快速代码检查 | | | Mypy mypy app/ | 类型检查 | | | Pytest pytest | 测试 |

______________________________________________________________________

|

🗺️ 路线图

• 第一阶段：核心功能 ✅
• \[x\] 身份验证与令牌管理
• \[x\] 项目列表及详情
• \[x\] 用户故事的增删改查（CRUD）操作
• \[x\] 任务管理
• \[x\] 团队成员名单
• \[x\] 智能分页

\[x\] 灵活的标识符（ID/别名/#引用）

• 第二阶段：增强功能🚧
• \[ \] 缓存层（Redis/内存中）
• \[ \] 限速
• \[ \] 批量操作
• \[ \] 极致支持
• \[ \] 敏捷冲刺/里程碑管理
• \[ \] 问题/错误跟踪
• \[ \] 维基页面集成
• \[ \] 文件附件
• \[ \] 对故事/任务的评论
• \[ \] 支持自定义字段

\[ \] 活动历史追踪

• 第三阶段：高级功能🎯
• \[ \] 独立的命令行界面（CLI）工具
• \[ \] 分析与报告
• \[ \] 数据导出/导入
• \[ \] 支持Webhook
• \[ \] 通知集成（Slack、电子邮件）
• \[ \] 项目模板
• \[ \] 消耗图（或：燃尽图）

______________________________________________________________________

\[ \] 时间追踪

🤝 贡献/参与

1. 欢迎投稿！以下是开始投稿的步骤：
2. 为仓库创建分支（或“克隆仓库”）创建一个特性分支 git checkout -b feature/amazing-feature
3. ：
4. 进行你的更改添加测试
5. 确保新代码的覆盖范围进行质量检查

   black app/ tests/
   ruff check app/ tests/
   mypy app/
   pytest

1. :提交您的更改 git commit -m 'Add amazing feature'
2. ：推送到分支 git push origin feature/amazing-feature
3. ：

打开一个拉取请求

• 发展指南
• 遵循现有的代码风格（使用Black格式化）
• 为所有函数添加类型提示
• 为公共API编写文档字符串
• 包含新功能的测试

______________________________________________________________________

根据需要更新文档

📝 许可证 此项目遵循GNU通用公共许可证v3.0授权——详见 许可证

______________________________________________________________________

文件中有详细信息。

• 🙏 致谢 模型上下文协议
• - 为卓越的大语言模型（LLM）工具集成标准 泰加（或泰加林）
• - 用于强大的开源项目管理平台 Anthropic（公司名，可译为“安萨里克”或根据具体语境保留原名）
• - 适用于Claude和MCP SDK 社区贡献者

______________________________________________________________________

- 为了收集反馈和进行改进

• 📞 支持文档 ： RUN.md（注：这通常是一个Markdown文件名，表示运行说明或运行指令，具体翻译可能根据上下文调整，但直接翻译即为“运行说明.md”或保持原样作为文件名）
• 用于设置指南问题 :
• GitHub Issues（在GitHub上报告的问题）讨论 ：
• GitHub 讨论区Taiga API 文档 ：

______________________________________________________________________

https://docs.taiga.io/api.html 的中文翻译为：“https://docs.taiga.io/（Taiga的）API文档页面”。不过，通常我们不会直接翻译网址，而是说明其内容或用途。所以，也可以表述为：“这是Taiga的API文档页面链接”

为AI赋能的项目管理社区倾心打造

______________________________________________________________________

⭐ 如果你觉得这个仓库有用，就给它点个星吧！

⚠️ 免责声明