Gitlab MCP Project Issue

GitLab MCP用于问题管理

 

这个项目是从 cayiteromer/gerrit代码审查mcp 适用于GitLab问题管理。

MCP（模型上下文协议）服务器，用于将Claude等人工智能助手与GitLab的问题跟踪系统集成。这允许AI助手通过自然语言命令管理、跟踪GitLab问题并与之交互。

特性

该MCP提供：

• 问题列表和筛选：通过按状态、标签、受让人、作者等进行强大筛选，列出项目问题
• 发出CRUD操作：创建、读取、更新和删除问题，并完全控制所有属性
• 评论与讨论：向问题添加评论并查看评论线程
• 状态管理：根据需要打开、关闭和重新打开问题
• 进行集成：为问题创建待办事项，以跟踪个人行动项
• 时间追踪：记录所花费的时间并设定问题的时间估计
• 问题链接：将相关问题链接在一起（相关、阻止、被阻止）
• 标签和里程碑管理：用标签和里程碑组织问题
• 高级功能：在项目之间移动问题、订阅通知等

视觉

此MCP服务器旨在通过与AI助手的自然语言交互，使GitLab问题管理变得可访问。您可以简单地要求人工智能助手：

• “显示分配给团队的所有关键错误”
• “为我们讨论的身份验证错误创建一个问题”
• “关闭所有重复问题并将其链接到原始问题”
• “问题#42的状态如何？”
• “为第15期增加2小时的工作时间”

这使得问题跟踪更加高效，并与人工智能助手无缝集成到您的对话工作流程中。

用例

• 项目管理：通过AI助手快速分类和组织问题
• 开发工作流程：在不离开IDE或聊天的情况下创建和更新问题
• 报告：了解问题状态、时间跟踪和团队工作量
• 自动化：构建基于人工智能的问题管理工作流程
• 文档：让你的AI助手在GitLab发布时跟踪待办事项和行动项

安装

先决条件

• Python 3.10+
• 具有API作用域的GitLab个人访问令牌（read_API，API）
• Cursor IDE 或 Claude桌面应用程序 用于MCP集成

快速开始

1. 克隆此存储库：

git clone https://github.com/yourusername/gitlab-mcp-project-issue.git
cd gitlab-mcp-project-issue

1. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 安装依赖项：

pip install -r requirements.txt

1. 创建一个 .env 包含GitLab配置的文件（请参阅 .env.example 对于所有选项）：

# Required
GITLAB_TOKEN=your_personal_access_token_here

# Optional settings
GITLAB_HOST=gitlab.com
GITLAB_API_VERSION=v4
LOG_LEVEL=INFO

配置选项

以下环境变量可以在您的 .env 文件：

游标IDE集成

要将此MCP与Cursor IDE一起使用，请将此配置添加到您的 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "gitlab-mcp-issue-management": {
      "command": "/path/to/your/gitlab-mcp-project-issue/.venv/bin/python",
      "args": [
        "/path/to/your/gitlab-mcp-project-issue/server.py",
        "--transport",
        "stdio"
      ],
      "cwd": "/path/to/your/gitlab-mcp-project-issue",
      "env": {
        "PYTHONPATH": "/path/to/your/gitlab-mcp-project-issue",
        "VIRTUAL_ENV": "/path/to/your/gitlab-mcp-project-issue/.venv",
        "PATH": "/path/to/your/gitlab-mcp-project-issue/.venv/bin:/usr/local/bin:/usr/bin:/bin"
      },
      "stdio": true
    }
  }
}

替换 /path/to/your/gitlab-mcp-project-issue 使用克隆存储库的实际路径。

Claude桌面应用程序集成

要将此MCP与Claude桌面应用程序一起使用：

1. 打开克劳德桌面应用程序
2. 转到“设置”→ 高级→ MCP配置
3. 添加以下配置：

{
  "mcpServers": {
    "gitlab-mcp-issue-management": {
      "command": "/path/to/your/gitlab-mcp-project-issue/.venv/bin/python",
      "args": [
        "/path/to/your/gitlab-mcp-project-issue/server.py",
        "--transport",
        "stdio"
      ],
      "cwd": "/path/to/your/gitlab-mcp-project-issue",
      "env": {
        "PYTHONPATH": "/path/to/your/gitlab-mcp-project-issue",
        "VIRTUAL_ENV": "/path/to/your/gitlab-mcp-project-issue/.venv",
        "PATH": "/path/to/your/gitlab-mcp-project-issue/.venv/bin:/usr/local/bin:/usr/bin:/bin"
      },
      "stdio": true
    }
  }
}

替换 /path/to/your/gitlab-mcp-project-issue 使用克隆存储库的实际路径。

可用工具

存储库工具

核心问题操作

评论与讨论

任务管理

时间追踪

问题关系

看 todo-plan.md 完整的实施路线图。

用法示例

问题管理工作流

通过自然语言与以下示例工作流交互GitLab问题：

列出问题

# Get all open issues in a project
issues = list_project_issues("123", state="opened")

# Get issues assigned to a specific user
my_issues = list_project_issues("123", assignee_id=456)

# Search for issues containing specific text
bugs = list_project_issues("123", labels="bug", search="login")

# Get recently updated issues
recent = list_project_issues("123", order_by="updated_at", sort="desc")

创建和管理问题

# Create a new issue
issue = create_issue(
    "123",
    title="Fix login page error",
    description="Users are experiencing errors on the login page",
    labels="bug,high-priority",
    assignee_ids=[456]
)

# Update an existing issue
updated = update_issue(
    "123",
    issue_iid="42",
    title="Updated title",
    add_labels="security",
    milestone_id=5
)

# Close an issue
closed = close_issue("123", 42)

# Reopen an issue
reopened = reopen_issue("123", 42)

# Add a comment to an issue
comment = add_issue_comment("123", "42", "Review completed - looks good!")

# List all comments on an issue
comments = list_issue_comments("123", "42")

# Create a to-do item for an issue
todo = create_issue_todo("123", 42)

# Link two issues together
link = link_issues("123", 42, "123", 15, link_type="relates_to")

# Create a blocking relationship
link = link_issues("123", 42, "123", 15, link_type="blocks")

# List all linked issues
links = list_issue_links("123", 42)

自然语言交互

有了像克劳德这样的人工智能助手，你可以使用自然语言：

• “显示分配给我的所有打开的Bug”
• “创建修复身份验证错误的问题”
• “更新问题#42以添加高优先级标签”
• “关闭问题#15”
• “重新打开问题#20”
• “列出项目123中包含‘安全’一词的所有问题”
• “在问题#42中添加注释，说明代码审查看起来不错”
• “显示对问题#15的所有评论”
• “将问题#42添加到我的待办事项列表中”
• “从项目中删除问题#99”
• “将问题#42链接到问题#15作为相关问题”
• “将问题#42标记为阻塞问题#15”
• “显示与问题#42相关的所有问题”

故障排除

如果您遇到问题：

1. 验证权限：您的GitLab令牌需要适当的权限：

- api 完全访问范围（创建、更新、删除问题） - read_api 只读操作范围（列出、查看问题） - 大多数操作至少需要 记者 项目访问权限 - 删除问题需要 管理员 或 项目负责人 访问

1. 检查配置:

- 验证 .env 文件设置正确 - 确保MCP配置路径指向正确的目录 - 确认您的GitLab令牌有效且未过期

1. 测试连接:

   curl -H "Private-Token: your-token" https://gitlab.com/api/v4/projects

1. 启用调试日志记录:

集 LOG_LEVEL=DEBUG 在你的 .env 详细日志记录文件

1. 常见问题:

- 403禁止：检查您对项目的访问级别 - 404未找到：验证项目ID和问题IID是否正确 - 401未经授权：您的令牌可能无效或已过期

贡献

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

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

请参阅 贡献.md 有关开发过程的更多详细信息，请参阅文件。

许可证

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