Jira Weekly Reporter MCP 服务器

该项目提供了一个 FastMCP 服务器，该服务器连接到您的 Jira 实例（云或服务器/数据中心），以根据问题活动生成每周报告。它利用 pycontribs-jira 库进行 Jira 交互，并可选择性地使用连接客户端的大型语言模型 (LLM) 来总结生成的报告。

✨ 特性

• Jira 连接： 使用存储在 .env 文件中的 API 令牌安全地连接到 Jira。
• MCP 工具： 通过 Model Context Protocol 提供一个 generate_jira_report 工具。
• 灵活的报告：
  • 默认报告过去 7 天内更新的问题。
  • 允许指定自定义 JQL 查询。
  • 可以按特定的 Jira 项目键过滤报告。
  • 限制返回的结果数量（可配置）。
• （可选）LLM 摘要： 可以使用客户端的 LLM（通过 ctx.sample()）来提供报告的简洁摘要。
• 异步处理： 在异步 FastMCP 服务器中正确处理同步 Jira 库调用，使用 asyncio.to_thread。

📋 前提条件

• Python 3.10 或更高版本。
• uv（推荐）或 pip 用于包管理。
• 访问 Jira 实例（云、服务器或数据中心）。
• Jira API 令牌（对于服务器/数据中心的个人访问令牌）。
• 安装了 FastMCP CLI 并且在系统 PATH 中可用。

⚙️ 设置

1. 克隆仓库（如果适用）：
   bash
   git clone https://github.com/Jongryong/jira_reporter.git
   cd jira_reporter

2. 安装依赖项：
   我们推荐使用 uv：
   bash
   uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio

   或者，使用 pip：
   bash
   pip install fastmcp "jira[cli]" python-dotenv httpx anyio

3. 创建 .env 文件：
   在与 jira_reporter_server.py 相同的目录中创建一个名为 .env 的文件。添加您的 Jira 连接详细信息：
   dotenv

   .env

   JIRA_URL=https://your-domain.atlassian.net # 您的 Jira 云 URL 或自托管 URL
   JIRA_USERNAME=your_email@example.com # 您的 Jira 登录电子邮件
   JIRA_API_TOKEN=your_api_token_or_pat # 您生成的 API 令牌或 PAT

   • 安全性：
     • 切勿将 .env 文件提交到版本控制！ 将 .env 添加到您的 .gitignore 文件中。
     • Jira 云： 从您的 Atlassian 账户设置中生成 API 令牌：管理 API 令牌。
     • Jira 服务器/数据中心： 从您的 Jira 用户配置文件设置中生成个人访问令牌 (PAT)：使用个人访问令牌。

▶️ 运行服务器（独立模式）

您可以独立运行服务器进行测试或其他目的：

1. 直接使用 Python：
   bash
   python jira_reporter_server.py

2. 使用 FastMCP CLI：
   bash
   fastmcp run jira_reporter_server.py

   若要使用 SSE（例如，远程访问）运行：
   bash
   fastmcp run jira_reporter_server.py --transport sse --port 8001

🖥️ 与 Claude Desktop 一起使用

要使此服务器作为工具在 Claude Desktop 应用程序中可用：

1. 确保满足前提条件： 确保 fastmcp 已安装并在系统的 PATH 中可用，因为下面的配置使用了 fastmcp 命令。2. 定位Claude配置文件： 找到claude_desktop_config.json文件。其位置取决于您的操作系统：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json（通常为 C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json）
   • Linux: ~/.config/Claude/claude_desktop_config.json（或 $XDG_CONFIG_HOME/Claude/）

2. 编辑配置文件： 使用文本编辑器打开claude_desktop_config.json。

3. 添加服务器配置： 在JSON中找到"mcpServers"对象（如果不存在，则创建一个空对象{}）。在mcpServers内部添加以下条目，确保将"path/to/your/jira_reporter_server.py"替换为您脚本的绝对路径：

   json
   {
   "mcpServers": {
   // ... 其他服务器可能在这里 ...

    "jira_report": {
      "command": "fastmcp",
      "args": [
        "run",
        "/path/to/your/jira_reporter_server.py" // <-- 重要：此处使用完整的绝对路径
      ]
    }
   
    // ... 其他服务器可能在这里 ...
   

   }
   // ... Claude配置的其余部分 ...
   }

   • "jira_report": 这是Claude使用的内部名称。如果您愿意，可以更改它。
   • "command": "fastmcp": 告诉Claude使用fastmcp命令行工具。
   • "args": [...]: 告诉Claude运行fastmcp run /path/to/your/jira_reporter_server.py。

4. 保存并重启： 保存claude_desktop_config.json文件并重新启动Claude Desktop应用程序。

5. 调用工具： 现在您应该能够通过提及Python脚本中定义的服务器名称（如Jira Weekly Reporter）来在Claude中使用该工具。例如：
   @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ MCP 工具详情

• 工具名称： generate_jira_report
• 描述： 根据JQL查询生成Jira问题报告（默认为最近更新的问题）。可选地，使用客户端的LLM对报告进行总结。

参数：

📦 服务器依赖项

FastMCP构造函数包括dependencies=["jira"]。这告诉像fastmcp install这样的工具，在创建隔离环境时需要jira库才能使此服务器正常工作。

🤝 贡献

欢迎贡献！请随时提交问题或拉取请求。

📄 许可证

MIT许可证