JIRA MCP Server 🚀

JIRA MCP 服务 🚀

这是一个灵活的 Go 服务，实现了 Model Context Protocol（MCP），可与 JIRA Cloud REST API 交互，让大模型/工具与您的 JIRA 项目无缝集成。

这是什么？🤔

该项目在使用 Model Context Protocol 的系统（例如某些 AI 助手或开发工具）与强大的 JIRA Cloud API 之间搭建桥梁。它允许您通过标准化的 MCP 接口，以编程方式执行常见的 JIRA 操作（创建问题、搜索、获取详情），无需直接处理复杂的 JIRA API 调用。

✨ 功能

• **MCP 接口：**通过标准 MCP 端点提供 JIRA 操作。
• **JIRA Cloud 集成：**创建问题、使用 JQL 搜索、获取问题详情，以及获取 Epic 下的问题。
• **灵活配置：**使用 Viper 通过环境变量、配置文件或默认值进行配置。
• **Docker 支持：**可通过 Docker 和 Docker Compose 进行容器化部署。
• **全面测试：**包含全面的单元测试和集成测试。
• **结构化日志：**使用 slog 输出清晰的结构化日志。
• **依赖注入：**采用整洁架构原则，并使用 wire 进行依赖注入。

前置条件

• Go 1.20+（用于本地构建/运行）
• Docker 和 Docker Compose（可选，用于容器化部署）
• JIRA Cloud 实例
• 与用户邮箱关联的 JIRA API Token

🚀 开始使用

1. 克隆仓库：

   git clone https://github.com/karolswdev/jira-mcp-server.git # TODO: Replace with actual URL
   cd jira-mcp-server # e.g., cd jira-mcp
   

2. 进入服务目录：

   cd jira-mcp-server
   

   **➡️ 重要：**后续大多数命令（make ...、go run ...、docker ...）都应在 jira-mcp-server/ 目录内运行。

3. **配置服务：**设置所需的环境变量或创建 config.yaml。请参阅下方的配置部分。

4. **运行服务：**请参阅下方的运行服务部分。

⚙️ 配置

配置使用 Viper 管理，并按以下优先级顺序从相应来源加载：

1. 环境变量： 添加 JIRA_MCP_ 前缀（例如，JIRA_MCP_JIRA_URL）。优先级最高。
2. 配置文件： 位于 jira-mcp-server/ 目录中的 config.yaml（或 .json、.toml）。有关结构和所有选项，请参阅 config.yaml.example。
3. 默认值： 应用程序代码中定义的默认值。

必需配置：

必须通过环境变量或配置文件提供以下值：

• JIRA_MCP_JIRA_URL：JIRA Cloud 实例的基础 URL（例如，https://your-domain.atlassian.net）。
• JIRA_MCP_JIRA_USER_EMAIL：与 API 令牌关联的 JIRA 用户电子邮件地址。
• JIRA_MCP_JIRA_API_TOKEN：JIRA API 令牌。请像密码一样妥善保管！

可选配置：

• JIRA_MCP_PORT：服务监听的端口（默认值：8080）。
• JIRA_MCP_LOG_LEVEL：日志级别（debug、info、warn、error）（默认值：info）。
• JIRA_MCP_EPIC_LINK_FIELD_ID：JIRA 实例中“Epic Link”的自定义字段 ID（例如，customfield_10014）。要使 /jira_epic/{epicKey}/issues 端点正常工作，必须配置此项。可通过 JIRA API 或管理设置查找此 ID。

示例（环境变量）：

export JIRA_MCP_JIRA_URL="https://your-domain.atlassian.net"
export JIRA_MCP_JIRA_USER_EMAIL="[email protected]"
export JIRA_MCP_JIRA_API_TOKEN="your-api-token-secret"
export JIRA_MCP_PORT="9000" # Optional
export JIRA_MCP_EPIC_LINK_FIELD_ID="customfield_10014" # Optional but needed for Epic endpoint

▶️ 运行服务

请确保当前位于 jira-mcp-server/ 目录中，并已配置必需设置。

选项 1：直接运行（使用 Go）

# Ensure required JIRA_MCP_... environment variables are set
make run
# Or: go run ./cmd/main.go

服务将开始在配置的端口上监听（默认端口为 8080）。

选项 2：使用 Docker 运行

1. 构建 Docker 镜像：

   make docker-build
   

2. 创建 .env 文件： 在 jira-mcp-server/ 目录内创建名为 .env 的文件，其中包含 JIRA_MCP_ 环境变量（每行一个，例如，JIRA_MCP_JIRA_URL=...）。

   # .env 文件内容示例
   JIRA_MCP_JIRA_URL=https://your-domain.atlassian.net
   [email protected]
   JIRA_MCP_JIRA_API_TOKEN=your-api-token-secret
   JIRA_MCP_PORT=8080 # 可选；如有更改，请确保与 docker-compose.yml 中的映射一致
   JIRA_MCP_EPIC_LINK_FIELD_ID=customfield_10014 # 可选
   

3. 使用 Docker Compose 运行：

   make docker-run
   # 此命令会使用 docker-compose up -d
   

   要停止容器：docker-compose down

🔌 API 端点

服务提供以下主要端点：

• POST /create_jira_issue：创建新的 JIRA 问题。
• POST /search_jira_issues：使用 JQL 搜索 JIRA 问题。
• GET /jira_issue/{issueKey}：获取指定 JIRA 问题的详细信息。
• GET /jira_epic/{epicKey}/issues：获取属于指定 Epic 的所有问题（需要配置 JIRA_MCP_EPIC_LINK_FIELD_ID）。

请求与响应示例

有关各端点的详细请求和响应示例，请参阅：

➡️ API_EXAMPLES.md

✅ 测试

项目包含单元测试和集成测试。请在 jira-mcp-server/ 目录中运行以下命令：

• 运行单元测试： 单独测试各个组件（模拟 JIRA API）。

  make test
  

• 运行集成测试： 针对模拟的 JIRA 服务测试 HTTP API 层。

  make test-integration
  

• 查看单元测试覆盖率： 生成 coverage.html 并在浏览器中打开。

  make coverage
  

• 查看集成测试覆盖率： 生成 coverage-integration.html 并在浏览器中打开。

  make coverage-integration
  

🏗️ 架构

此服务遵循整洁架构原则，采用依赖注入（wire）、结构化日志（slog）以及分层职责分离（处理程序、JIRA 客户端、核心逻辑）。

如需了解更详细的说明，请参阅 架构文档。

🤝 贡献

欢迎并非常感谢您参与贡献！无论是报告错误、提出功能建议、改进文档，还是提交拉取请求，您的帮助都能让此项目变得更好。

请阅读我们的 贡献指南，了解如何开始。

此外，请注意，此项目遵循 贡献者行为准则 发布。参与此项目即表示您同意遵守其中的条款。

📜 许可证

此项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

⚠️ 安全提示

切勿将 JIRA API 令牌或其他敏感凭据直接提交到版本控制中的代码或配置文件。 请使用环境变量或安全的密钥管理系统，尤其是在生产环境部署时。请确保将 .env 文件（如用于 Docker）添加到 .gitignore 中。