Jira 洞察 MCP 服务器

项目概述

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

功能特性

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

先决条件

1. 安装 Node.js 和 npm（推荐版本为 Node 16.x 或以上）。
2. 安装 Docker（用于 Docker 部署）。
3. 获取 Jira API 访问令牌，并确保其具有必要的权限。

安装指南

本地开发安装

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 镜像以生效更改。
• 使用环境变量避免硬编码敏感信息。

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