Jira Insights MCP

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

上次更新：2025-03-20

概述

此 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

构建 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 镜像
./scripts/build-local.sh

# 运行 Docker 容器
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. 对象类型属性问题

   • 将“expand”参数与“attributes”一起使用时，请确保对象类型存在
   • 检查您是否具有查看属性的权限

3. API 连接问题

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

许可证

MIT