Jira Assistant with MCP Integration

Jira Assistant with MCP Integration

一个基于 Streamlit 的 Jira 工单管理助手，使用 MCP (Model Control Panel) 进行工具调用。

功能

• 🤖 不同操作的简洁标签页界面
• 🎯 使用简单对话命令创建、搜索和管理 Jira 工单
• 🔄 实时工单创建，无需依赖外部大模型
• 🛠️ 基于 MCP 框架构建，支持灵活的工具调用
• 📊 直接的表单界面，用于创建和搜索工单

截图

标签页界面

该应用现在具有简洁的标签页界面，包括以下独立部分：

1. Chat - 用于管理工单的对话界面
2. Create Ticket - 基于表单的工单创建
3. Search Tickets - 使用 JQL 的高级搜索

前置要求

• Python 3.8+
• 具有 API 访问权限的 Jira 账户
• 运行中的 MCP 服务器（配有 Jira 工具）

安装

1. 克隆仓库
2. 安装所需的包：

   pip install -r requirements.txt
   

3. 在 .env 文件中设置环境变量：

   JIRA_URL=https://your-domain.atlassian.net
   [email protected]
   JIRA_API_TOKEN=your-jira-api-token
   

运行应用程序

使用启动脚本启动应用程序：

./start_jira_assistant.sh

该脚本将：

1. 检查是否安装了 MCP 包
2. 验证所需的环境变量
3. 如果 MCP 服务器尚未运行，启动它
4. 启动 Streamlit 应用程序

使用示例

创建工单

你可以通过两种方式创建工单：

使用聊天界面

输入自然语言命令，例如：

• "Create a new task in KAN titled 'Implement user authentication' with description 'We need to add a JWT-based authentication system for user login.'"
• "I need a bug ticket in KAN for 'Fix pagination in user list' describing 'The pagination controls are not working correctly when there are more than 10 users.'"

使用表单界面

1. 导航到"Create Ticket"标签页
2. 填入必需字段（项目密钥、摘要、描述）
3. 选择问题类型
4. 点击"Create Ticket"

搜索工单

你可以通过两种方式搜索工单：

使用聊天界面

输入自然语言查询，例如：

• "Find all open tickets in the KAN project"
• "Show me all high priority bugs"
• "Search for tickets mentioning 'authentication' in the KAN project"

使用搜索界面

1. 导航到"Search Tickets"标签页
2. 输入 JQL 查询（界面中提供了示例）
3. 设置最大结果数
4. 点击"Search"

获取工单详情

询问特定工单的详情：

• "Show details for ticket KAN-123"
• "What's the status of KAN-456?"

直接 Jira 工具

对于命令行操作，使用 direct_jira_tool.py 脚本：

# List available tools
./direct_jira_tool.py list

# Create a ticket
./direct_jira_tool.py create --project KAN --title "Fix login page" --description "The login page has a UI bug in Safari"

# Search for tickets
./direct_jira_tool.py search --query "project = KAN AND status = 'In Progress'"

# Get ticket details
./direct_jira_tool.py get --id KAN-123

测试 MCP 客户端

你可以使用 test_mcp_client.py 脚本测试与 MCP 服务的连接：

# Run all tests
python test_mcp_client.py all

# Test connection only
python test_mcp_client.py connect

# Test creating a specific ticket
python test_mcp_client.py test_create --project KAN --title "Test ticket" --description "This is a test"

故障排除

MCP 服务问题

如果 MCP 服务连接不正常：

1. 检查 MCP 服务路径是否正确
2. 验证 .env 文件中的 Jira 凭证
3. 使用侧边栏中的"Restart MCP Server"按钮
4. 使用 test_mcp_client.py connect 测试连接

工单创建问题

如果遇到工单创建问题：

1. 确保所有必需字段都已填入
2. 检查项目密钥是否存在且格式正确
3. 验证你的 Jira API 令牌是否有足够的权限
4. 在响应中查找具体的错误消息

搜索问题

如果遇到搜索问题，出现类似 Error executing tool search_jira_tickets: validation error 的错误消息：

1. 确保你的 JQL 查询格式正确
2. 避免使用包含特殊字符的复杂 JQL 查询
3. 先尝试简单查询（如 project = KAN）来测试功能
4. MCP 服务器目前限制每次搜索最多返回 10 个结果

其他问题

• 检查浏览器控制台和终端输出以获取详细的错误消息
• 确保所有环境变量设置正确
• 确保安装了正确版本的 mcp 软件包（pip install -U mcp）

最新更新中的新功能

• 📋 选项卡式界面：为聊天、工单创建和搜索提供独立选项卡
• 🖋️ 改进的工单创建：无需依赖大模型的直接表单创建
• 🔎 高级搜索：基于 JQL 的搜索，包含示例和灵活的格式化
• 🛡️ 增强的错误处理：更好的错误消息和验证
• 🧩 简化的依赖项：移除了对 Gemini 等外部 API 的依赖

开发

要为此项目做出贡献：

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 提交拉取请求

许可证

此项目在 MIT 许可证下许可 - 详见 LICENSE 文件。

致谢

• Streamlit，用于网络应用框架
• MCP，用于工具调用基础设施