AI导哈

JIRA MCP服务器

一个灵活的Go服务器，实现模型上下文协议（MCP）与JIRA Cloud REST API交互，为LLM/工具与JIRA项目提供无缝集成。

  • by karolswdev
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 karolswdev/jira-mcp-server

使用说明

JIRA MCP服务器🚀

一个灵活的Go服务器，实现模型上下文协议（MCP）与JIRA Cloud REST API交互，实现LLM/工具与JIRA项目之间的无缝集成。

这是什么？ 🤔

该项目在使用模型上下文协议（如某些人工智能助手或开发工具）的系统和强大的JIRA Cloud API之间提供了一座桥梁。它允许您通过标准化的MCP接口以编程方式执行常见的JIRA操作（创建问题、搜索、检索详细信息），从而抽象出直接JIRA API调用的复杂性。

✨ 特性

  • MCP接口： 通过标准MCP端点公开JIRA操作。
  • JIRA云集成： 在Epic中创建问题、使用JQL搜索、检索问题详细信息和获取问题。
  • 灵活配置： 使用Viper通过环境变量、配置文件或默认值进行配置。
  • Docker支持： 已准备好使用Docker和Docker Compose进行容器化部署。
  • 稳健测试： 包括全面的单元和集成测试。
  • 结构化日志记录： 用途 slog 用于清晰、结构化的日志记录。
  • 依赖注入： 采用干净的建筑原则，使用 wire 用于依赖注入。

先决条件

  • 转到1.20+（用于本地构建/运行）
  • Docker和Docker Compose（可选，用于容器化部署）
  • JIRA云实例
  • 与用户电子邮件关联的JIRA API令牌

🚀 入门指南

  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. 运行服务器： 请参阅 运行服务器 下面的部分。

⚙️ 配置

配置是通过以下方式进行管理的 蝰蛇 并按优先级顺序从以下来源加载：

  1. 环境变量： 前缀为 JIRA_MCP_ （例如。， JIRA_MCP_JIRA_URL). 最高优先级。
  2. 配置文件： config.yaml （或 .json, .toml)位于 jira-mcp-server/ 目录。看 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="your.email@example.com"
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 文件： 创建一个名为的文件 .env 里面 jira-mcp-server/ 目录 包含您的 JIRA_MCP_ 环境变量（每行一个。， JIRA_MCP_JIRA_URL=...).
    # .env file content example
JIRA_MCP_JIRA_URL=https://your-domain.atlassian.net
JIRA_MCP_JIRA_USER_EMAIL=your.email@example.com
JIRA_MCP_JIRA_API_TOKEN=your-api-token-secret
JIRA_MCP_PORT=8080 # Optional, ensure it matches docker-compose.yml mapping if changed
JIRA_MCP_EPIC_LINK_FIELD_ID=customfield_10014 # Optional
  3. 使用Docker Compose运行：
    make docker-run
# This command uses 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许可证获得许可。请参阅 许可证 文件以获取详细信息。

⚠️ 安全说明

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

相关 MCP