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

1. 安装依赖项：

   npm install

1. 构建项目：

   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. 增强的错误处理

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

1. AQL查询改进

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

1. 属性发现增强

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

中等优先级改进

1. 对象模板生成

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

1. 示例查询库

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

1. 改进文档

- 增强的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) - 检查您的架构中是否存在对象类型和属性

1. 对象类型属性问题

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

1. API连接问题

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

许可证

麻省理工学院