Jira Insights MCP

🚀 Jira 洞察 MCP 服务器

本项目是一个用于管理 Jira Insights 资产模式的模型上下文协议 (MCP) 服务器。它提供了对资产模式、对象类型和属性的增删改查功能，还支持通过 AQL 查询进行数据检索，极大地提升了 Jira Insights 资产模式的管理效率。

🚀 快速开始

本服务器是用于管理 Jira Insights 资产模式的 MCP 服务器，提供资产模式、对象类型和属性的增删改查功能，支持 AQL 查询进行数据检索。使用前需完成先决条件的准备，再按照安装指南进行安装。

✨ 主要特性

• 资产模式管理：支持创建、读取、更新和删除资产模式。
• 对象类型管理：提供对象类型的全量和增量信息，包括属性扩展。
• 属性管理：允许获取单个属性或多个属性的详细信息，并支持按名称搜索属性。
• AQL 查询：通过 AQL 语法进行复杂的数据检索。

📦 安装指南

本地开发安装

1. 克隆代码库：

   git clone [仓库地址]
   cd jira-insight-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 启动服务器：

   npm start
   

Docker 部署

1. 构建 Docker 镜像：

   ./scripts/build-local.sh
   

2. 运行容器：

   ./scripts/run-local.sh
   

💻 使用示例

服务器配置

可以通过环境变量或配置文件来设置以下参数：

• JIRA_API_TOKEN：Jira API 访问令牌。
• JIRA_HOST_URL：Jira 实例的 URL 地址。

基础用法

# 设置环境变量并启动容器
export JIRA_API_TOKEN="your_token_here"
export JIRA_HOST_URL="https://your-jira-instance.atlassian.com"
docker-compose up

📚 详细文档

工具集

资产模式管理工具

• 命令：manage_jira_insight_schema
• 功能：
  • 创建新资产模式。
  • 获取指定 ID 的资产模式详细信息。
  • 更新现有资产模式。
  • 删除指定 ID 的资产模式。

对象类型管理工具

• 命令：manage_jira_object_type
• 功能：
  • 获取所有对象类型的完整或增量信息，支持 expand=attributes 参数。

属性管理工具

• 命令：manage_jira_attribute
• 功能：
  • 获取单个属性的详细信息。
  • 搜索匹配指定名称的多个属性。

资源概览

计划改进

高优先级改进

1. 增强错误处理：
   • 提供更详细的错误信息，包括具体的问题描述。
   • 增加错误修复建议和操作示例。
2. 优化 AQL 查询功能：
   • 添加查询验证和格式化工具。
   • 提供按模式定制的示例查询。
3. 改进属性发现机制：
   • 优化属性获取性能，增加缓存支持。
   • 改善 expand 参数的处理逻辑。

中等优先级改进

1. 对象模板生成：
   • 根据对象类型自动生成创建模板。
   • 提供占位符示例和验证规则。
2. 查询库优化：
   • 建立模式相关的查询示例库。
   • 实现上下文感知的查询建议功能。

开发指南

脚本使用

• npm run build：构建 TypeScript 代码。
• npm run lint：运行 ESLint 检查代码风格。
• npm run test：执行单元测试。
• npm run watch：开启实时代码监控和自动构建。

故障排除

常见问题

1. AQL 查询错误：
   • 确保使用双引号包裹含空格的值，例如 Name = "John Doe"。
   • 使用大写逻辑运算符如 AND、OR。
2. 属性获取失败：
   • 检查 API 访问令牌是否有效且权限足够。
   • 确认对象类型 ID 是否正确。

项目文件

• 配置文件：config/default.json
• 日志文件：logs/

注意事项

⚠️ 重要提示

修改代码后需重新构建 Docker 镜像以生效更改。

💡 使用建议

使用环境变量避免硬编码敏感信息。

更多详细信息请参考项目文档或联系开发团队。