AI导哈

Jira Insights管理协议

一个用于管理Jira Insights资产模式的Model Context Protocol服务器，支持对象模式、对象类型和对象的CRUD操作及AQL查询。

  • by aaronsb
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 aaronsb/jira-insights-mcp

使用说明

Jira Insights MCP

用于管理Jira Insights（JSM）资产模式的模型上下文协议（MCP）服务器。

最后更新时间：2025-04-09

概述

此MCP服务器提供了通过模型上下文协议与Jira Insights（JSM）资产模式交互的工具。它允许您在Jira Insights中管理对象模式、对象类型和对象。

特性

  • 管理对象模式（创建、读取、更新、删除）
  • 管理对象类型（创建、读取、更新、删除）
  • 管理对象（创建、读取、更新、删除）
  • 使用AQL（Atlassian查询语言）查询对象

先决条件

  • Node.js 20或更高版本
  • Docker（用于容器化部署）
  • 具有API访问权限的Jira Insights实例
  • 具有适当权限的Jira API令牌

安装

地方发展

  1. 克隆存储库：

    git clone https://github.com/aaronsb/jira-insights-mcp.git
cd jira-insights-mcp

  2. 安装依赖项：

    npm install

  3. 构建项目：

    npm run build

码头工人

构建Docker镜像：

./scripts/build-local.sh

用法

MCP配置

要将此MCP服务器与支持模型上下文协议的Claude或其他AI助手一起使用，请使用以下方法之一将其添加到MCP配置中：

本地构建配置

如果您在本地构建了项目，请使用以下配置：

{
  "mcpServers": {
    "jira-insights": {
      "command": "node",
      "args": ["/path/to/jira-insights-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "LOG_MODE": "strict"
      }
    }
  }
}

基于Docker的配置

如果你更喜欢使用Docker镜像（建议大多数用户使用），请使用以下配置：

{
  "mcpServers": {
    "jira-insights": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_API_TOKEN",
        "-e", "JIRA_EMAIL",
        "-e", "JIRA_HOST",
        "ghcr.io/aaronsb/jira-insights-mcp:latest"
      ],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_HOST": "https://your-domain.atlassian.net"
      }
    }
  }
}

这种基于Docker的配置从GitHub容器注册表中提取最新映像，并使用必要的环境变量运行它。

在当地发展

对于本地开发和测试：

# Build the Docker image
./scripts/build-local.sh

# Run the Docker container
JIRA_API_TOKEN=your_token JIRA_EMAIL=your_email JIRA_HOST=your_host ./scripts/run-local.sh

可用工具

manage_jira_insight_schema

使用CRUD操作管理Jira Insights对象模式。

{
  "operation": "list",
  "maxResults": 10
}

manage_jira_insight_object_type

使用CRUD操作管理Jira Insights对象类型。

{
  "operation": "list",
  "schemaId": "1",
  "maxResults": 20
}

manage_jira_insight_object

使用CRUD操作和AQL查询管理Jira Insights对象。

{
  "operation": "query",
  "aql": "objectType = \"Application\"",
  "maxResults": 10
}

可用资源

MCP服务器为访问Jira Insights数据提供了多种资源：

  • jira-insights://instance/summary -Jira Insights实例的高级统计数据
  • jira-insights://aql-syntax -资产查询语言（AQL）语法综合指南及示例
  • jira-insights://schemas/all -所有模式及其对象类型的完整列表
  • jira-insights://schemas/{schemaId}/full -包含对象类型的特定模式的完整定义
  • jira-insights://schemas/{schemaId}/overview -特定模式概述，包括元数据和统计信息
  • jira-insights://object-types/{objectTypeId}/overview -特定对象类型的概述，包括属性和统计信息

计划改进

我们正在进行几项改进，以增强Jira Insights MCP的功能和可用性：

高优先级改进

  1. 增强的错误处理

    • 具有特定验证问题的更详细的错误消息
    • 常见错误的建议修复
    • 操作具体示例，帮助用户纠正问题

  2. AQL查询改进

    • AQL查询的验证和格式化实用程序
    • 特定于模式的示例查询
    • 更好的查询问题错误消息

  3. 属性发现增强

    • 改进了对象类型的属性检索
    • 缓存以获得更好的性能
    • 更好地处理“expand”参数

中等优先级改进

  1. 对象模板生成

    • 基于对象类型创建对象的模板
    • 特定类型占位符生成
    • 模板中的验证规则

  2. 示例查询库

    • 特定于模式的示例查询
    • 上下文感知查询建议
    • 常见操作的查询模板

  3. 改进文档

    • 增强的AQL语法文档
    • 操作特定文件
    • 常见错误场景和解决方案

有关计划改进的更多详细信息，请参阅：

  • TODO.md -按优先级组织所有任务的综合待办事项列表
  • IMPLEMENTATION_PLAN.md -高优先级改进的详细实施计划
  • HANDLER_IMPROVEMENTS.md -每个处理程序文件所需的具体更改
  • IMPROVEMENT_SUMMARY.md -计划改进的简明摘要
  • docs/API_MIGRATION_TODO.md -API迁移的现状和计划的改进

发展

脚本

  • npm run build：构建TypeScript代码
  • npm run lint：运行ESLint
  • npm run lint:fix：运行ESLint并自动修复
  • npm run test：运行测试
  • npm run watch：观察变化并重建
  • npm run generate-diagrams：生成TypeScript依赖关系图

Docker脚本

  • ./scripts/build-local.sh：构建Docker镜像
  • ./scripts/run-local.sh：运行Docker容器

故障排除

常见问题

  1. AQL查询验证错误

    • 确保带空格的值括在引号中： Name = "John Doe"
    • 使用大写字母表示逻辑运算符： AND, OR （不是 and, or)
    • 检查您的架构中是否存在对象类型和属性

  2. 对象类型属性问题

    • 当使用带有“attributes”的“expand”参数时，确保对象类型存在
    • 检查您是否有查看属性的权限

  3. API连接问题

    • 验证您的Jira API令牌是否具有必要的权限
    • 检查Jira主机URL是否正确
    • 确保您的网络允许连接到Jira API

许可证

麻省理工学院

相关 MCP