Jira Insights MCP

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

上次更新时间：2025 年 4 月 9 日

概述

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

特征

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

先决条件

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

安装

本地开发

克隆存储库：
git clone https://github.com/aaronsb/jira-insights-mcp.git cd jira-insights-mcp
安装依赖项：
npm install
构建项目：
npm run build

Docker

构建 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 Container Registry 中提取最新的镜像并使用必要的环境变量运行它。

本地运行以进行开发

对于本地开发和测试：

# 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

可用工具

管理jira_insight_schema

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

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

管理jira_insight_object_type

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

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

管理jira_insight_对象

使用 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 的功能和可用性：

高优先级改进

增强错误处理
- 针对具体验证问题的更详细的错误消息
- 常见错误的修复建议
- 特定操作示例，帮助用户纠正问题
AQL 查询改进
- AQL 查询的验证和格式化实用程序
- 特定于架构的示例查询
- 针对查询问题的更好的错误消息
属性发现增强
- 改进了对象类型的属性检索
- 缓存以获得更好的性能
- 更好地处理“expand”参数

中优先级改进

对象模板生成
- 根据对象类型创建对象的模板
- 类型特定的占位符生成
- 模板中的验证规则
示例查询库
- 特定于架构的示例查询
- 上下文感知查询建议
- 常见操作的查询模板
改进的文档
- 增强的 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 容器

故障排除

常见问题

AQL 查询验证错误
- 确保带空格的值用引号引起来： Name = "John Doe"
- 对逻辑运算符使用大写： AND 、 OR （非and 、 or ）
- 检查模式中是否存在对象类型和属性
对象类型属性问题
- 当使用带有“attributes”的“expand”参数时，确保对象类型存在
- 检查您是否有权限查看属性
API 连接问题
- 验证您的 Jira API 令牌是否具有必要的权限
- 检查 Jira 主机 URL 是否正确
- 确保您的网络允许连接到 Jira API

执照

麻省理工学院

Jira Insights MCP

Integrations

Jira Insights MCP

概述

特征

先决条件

安装

本地开发

Docker

用法

MCP 配置

本地构建配置

基于Docker的配置

本地运行以进行开发

可用工具

管理jira_insight_schema

管理jira_insight_object_type

管理jira_insight_对象

可用资源

计划改进

高优先级改进

中优先级改进

发展

脚本

Docker脚本

故障排除

常见问题

执照

Tools