Skip to main content
Glama
JustWang1110

Jira AI Tool Server

by JustWang1110
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Jira AI Tool Server

一个面向后续插件化的大模型 Jira 能力内核。

当前状态

当前版本提供 17 个只读工具，外加 7 个受控写入 / 本地配置工具：

  • jira.search_issues

  • jira.get_issue

  • jira.get_comments

  • jira.get_transitions

  • jira.get_permissions

  • jira.get_project_snapshot

  • jira.find_stale_issues

  • jira.get_assignee_workload

  • jira.get_status_distribution

  • jira.find_high_priority_open_issues

  • jira.analyze_project_risks

  • jira.build_weekly_summary

  • jira.list_projects

  • jira.refresh_project_index

  • jira.resolve_project

  • jira.search_named_filter

  • jira.search_issues_by_filters

  • jira.upsert_name_mapping

  • jira.add_comment

  • jira.add_review_summary_comment

  • jira.transition_issue

  • jira.update_issue_fields

  • jira.sync_review_outcome

  • jira.ide_sync_review_outcome

并提供统一调度层：

  • ToolDispatcher.dispatch(tool_name, payload)

  • ToolDispatcher.list_tools()

  • ToolDispatcher.describe(tool_name)

以及一个最小 HTTP 服务：

  • GET /health

  • GET /tools

  • GET /tools/{tool_name}

  • POST /invoke/{tool_name}

运行时还会依据 schemas/ 中的输入契约执行校验；
这意味着模型或外部调用方即使构造了错误参数，也会先被拦在 dispatcher 层。

同样地，工具输出也会按 response schema 反向校验；
如果某个实现悄悄返回了不符合契约的结构，dispatcher 会把它收敛成 INVALID_TOOL_OUTPUT。

调用链路也已支持审计记录；HTTP 服务启动时可把事件追加写入 JSONL 文件， 为未来写操作、审批和排障保留事实依据。

Related MCP server: jira-mcp-server

目录

docs/       协议与说明
schemas/    JSON Schema
tools/      工具注册表
src/        最小可运行内核
tests/      基础测试

环境变量

JIRA_BASE_URL
JIRA_USERNAME
JIRA_PASSWORD
JIRA_TIMEOUT_SECONDS
HTTP_HOST
HTTP_PORT
AUDIT_FILE_PATH

本地配置文件

复制示例文件：

copy config\local.example.json config\local.json

第一次使用时，可在 config/local.json 里填写明文密码：

{
  "jira": {
    "base_url": "https://jira.example.com",
    "username": "your-username",
    "password": "首次启动前填写明文"
  }
}

项目启动后会自动移除明文字段，并改写为平台对应的安全引用：

  • Windows：使用 DPAPI，把密文写回配置文件

  • macOS：把密码写入系统 Keychain，配置文件只保存引用

因此：

  • Windows 密文通常只能由当前用户、当前机器解开

  • macOS 密码由 Keychain 代管，配置文件不再保存密码本体

config/local.json 已被加入 .gitignore，不要提交到仓库。

项目别名与缓存

为了让“昆山人民项目”这类口语化说法稳定映射到 Jira 项目， 配置文件支持维护人工别名：

{
  "projects": {
    "index_file_path": "data/project-index.json",
    "ttl_seconds": 86400,
    "aliases": {
      "昆山人民": "IHGS2512222C"
    }
  }
}

运行时默认优先读取本地索引；只有索引缺失、过期，或显式要求刷新时， 才会重新向 Jira 拉取项目列表。

项目分析工具同时支持：

{"project_key": "IHGS2512222C"}

或：

{"project_name": "昆山人民"}

当传入 project_name 时，工具内部会自动走本地索引与别名解析。

项目优先分单与路由规则（最小改造）

如果希望“某些项目优先分给固定人员”，可在 projects.directory 的项目条目中增加：

{
  "key": "IHZB2404585A",
  "name": "上海曙光医院安徽医院",
  "product_category": "RS6",
  "province": "安徽省",
  "preferred_assignee": "w_tang"
}

  • preferred_assignee：项目级优先处理人（Jira 账号）

  • 命中该字段后，可直接优先分配给该账号

  • 若未配置该字段，再走通用自动命中规则

配套的“最小改造版”路由配置可放在 local.json 根节点（与现有 projects、members 并列）：

{
  "routing": {
    "enabled": true,
    "project_preferred_assignee_field": "preferred_assignee",
    "match_order": [
      "project_preferred_assignee",
      "province_product_category_module",
      "province_product_category",
      "product_category_module",
      "module_only"
    ],
    "min_hit": 5,
    "effort_estimation": {
      "method": "mean",
      "source_field": "折算工时（小时）",
      "min_sample": 5,
      "fallback_order": [
        "province_product_category_module",
        "province_product_category",
        "product_category_module",
        "module_only",
        "product_category_global"
      ],
      "precision": 1
    },
    "outlier_filter": {
      "enabled": true,
      "lower_percentile": 5,
      "upper_percentile": 95
    },
    "scoring_weights": {
      "hit": 0.6,
      "efficiency": 0.25,
      "load": 0.15
    }
  }
}

带中文备注的可读版（示例）：

{
  "_comment": "分单命中规则配置（含工时预估）",
  "routing": {
    "enabled": true,
    "_comment_enabled": "总开关，false 时不启用自动分单",
    "project_preferred_assignee_field": "preferred_assignee",
    "_comment_project_preferred_assignee_field": "项目条目中的优先分配字段名",
    "match_order": [
      "project_preferred_assignee",
      "province_product_category_module",
      "province_product_category",
      "product_category_module",
      "module_only"
    ],
    "_comment_match_order": "命中顺序：从上到下依次尝试，命中即停止",
    "min_hit": 5,
    "_comment_min_hit": "候选人最小样本量，低于该值不参与排序",
    "effort_estimation": {
      "method": "mean",
      "_comment_method": "工时预估方式：平均折算工时",
      "source_field": "折算工时（小时）",
      "min_sample": 5,
      "_comment_min_sample": "样本不足时按 fallback_order 逐级回退",
      "precision": 1
    }
  }
}

命中流程示例（输入 Jira 单 -> 输出命中人 + 预估工时）

以下示例用于验证“项目优先分单 + 自动规则回退 + 平均工时预估”是否按预期工作。

输入（示例 Jira 单）：

{
  "issue_key": "L1NJ2007002C-855",
  "project_key": "L1NJ2007002C",
  "project_name": "华东-仪征市人民医院",
  "summary": "术语维护中的限制提醒，住院能正常弹窗，门诊未弹窗",
  "module": "HIS"
}

处理流程：

  1. 读取 projects.directory，按 project_key/project_name 定位项目元数据

  2. 检查是否存在 preferred_assignee

    • 若存在：直接命中该账号

    • 若不存在：进入自动规则

  3. 自动规则按 match_order 依次尝试命中：

    • province + product_category + module

    • province + product_category

    • product_category + module

    • module_only

  4. 在命中层级内按历史样本排序候选人（命中量、效率、负载）

  5. 预估工时按当前命中层级样本计算平均折算工时

    • 样本量小于 min_sample 时按 fallback_order 逐级回退

输出（示例）：

{
  "matched_by": "province_product_category_module",
  "assignee": "yu-ran",
  "assignee_source": "auto_rule",
  "estimated_hours": 3.1,
  "estimation_method": "mean(折算工时（小时）)",
  "sample_size": 134,
  "candidates_top3": [
    {"assignee": "yu-ran", "score": 126.72},
    {"assignee": "cheng.l.neu", "score": 119.86},
    {"assignee": "ji-t", "score": 79.42}
  ]
}

若项目配置了优先人（例如 preferred_assignee = w_tang），输出示例：

{
  "matched_by": "project_preferred_assignee",
  "assignee": "w_tang",
  "assignee_source": "project_config",
  "estimated_hours": 2.4,
  "estimation_method": "mean(同项目/同类样本)",
  "sample_size": 39
}

命名筛选器

对于“本地化问题”这类团队内部已有共识的概念，可直接在配置中固化：

{
  "named_filters": {
    "本地化问题": "resolution = Unresolved AND 问题分类 = 本地化"
  }
}

之后工具可用：

{
  "filter_name": "本地化问题",
  "project_name": "昆山人民",
  "module_name": "医生站",
  "extra_jql": "assignee is EMPTY"
}

也支持按项目属性做跨项目命名筛选统计：

{
  "filter_name": "本地化问题",
  "project_filters": {
    "product": "RS6"
  },
  "module_name": "医生站"
}

其中：

  • filter_name 表示问题性质，例如“本地化问题”

  • module_name 表示模块维度，底层会翻译成 Jira JQL 中的 component

  • project_filters 与 search_issues_by_filters 一致，支持 key/name/team/product/product_category/province/region/industry/owner

按 Jira 界面维度查询

如果你希望精确匹配界面筛选项，可直接使用：

{
  "project_name": "昆山人民",
  "statuses": ["待处理", "处理中"],
  "modules": ["医生站"],
  "issue_categories": ["本地化"],
  "assignees": ["晓刚"]
}

它会生成：

project = IHGS2512222C
AND status in (待处理, 处理中)
AND component in (医生站)
AND 问题分类 in (本地化)
AND assignee in (kuangxg)
ORDER BY priority DESC, updated DESC

如果你希望按项目属性做跨项目统计（例如统计 RS6 产品的问题总数），可在 ~/.jira-ai/local.json 的 projects.directory 维护项目元数据，然后在工具中传：

{
  "project_filters": {
    "product": "RS6"
  },
  "statuses": ["待处理", "处理中"],
  "max_results": 100
}

project_filters 支持字段：

  • key

  • name

  • team

  • product

  • product_category

  • province

  • region

  • industry

  • owner

每个字段支持传单个字符串或字符串数组；系统会先把匹配到的项目集合翻译成 project in (...)，再拼接其他 Jira 维度条件。

同样的 project_filters 也可用于以下工具，实现按属性维度的跨项目统计与分析：

  • jira.get_project_snapshot

  • jira.find_stale_issues

  • jira.get_assignee_workload

  • jira.get_status_distribution

  • jira.find_high_priority_open_issues

  • jira.analyze_project_risks

  • jira.build_weekly_summary

导出加班工作簿

可直接用本地 Jira 数据刷新固定模板：

python -m jira_ai.overtime_export --label 0622加班

默认会写回 C:\Users\MengWang\.jira-ai\第一交付服务中心加班工作任务一览表.xlsx，也可以通过 --workbook 和 --config 覆盖路径。

中文成员名映射

如果团队成员日常使用中文名沟通，建议在配置中维护成员映射：

{
  "members": {
    "aliases": {
      "晓刚": "kuangxg",
      "张三": "zhangsan"
    },
    "directory": [
      {
        "jira_username": "kuangxg",
        "display_name": "匡晓刚",
        "aliases": ["匡工"],
        "project_keys": ["IHGS2512222C"]
      }
    ]
  }
}

这样后续就可以直接说中文名。若模型没有匹配到成员，它会返回候选人，适合继续追问确认。

如需把新的中文别名写回本地配置，可调用：

{
  "mapping_type": "member",
  "alias": "晓刚",
  "target": "kuangxg",
  "display_name": "匡晓刚",
  "project_keys": ["IHGS2512222C"]
}

启动前自检

python -m jira_ai.doctor_cli

当前会检查：

  • 配置是否成功加载

  • Jira REST 服务是否可访问

首轮真实联调

当 doctor 通过后，可以直接执行：

python -m jira_ai.smoke_cli --issue-key PROJ-123 --project-key PROJ

它会依次验证：

  1. 权限检查

  2. 单任务读取

  3. 评论读取

  4. 当前可流转状态读取

  5. 项目内 JQL 搜索

本地验证

python -m unittest discover -s tests

插件构建与发布

构建最新 Codex 插件自包含包：

.\scripts\build-plugin.ps1

发布指定版本并生成 zip：

.\scripts\release-plugin.ps1 -Version 0.1.2

发布产物会输出到 dist/，其中包括：

  • jira-ai-codex-<version>.zip

  • jira-ai-codex-<version>-RELEASE.md

每次发布前，脚本会先同步 plugins/jira-ai-codex/bundle/，确保插件离开源码仓库后仍可独立运行。

完整发布流程见：

调用示例

from jira_ai.service import ToolDispatcher

dispatcher = ToolDispatcher.from_env()
result = dispatcher.dispatch(
    "jira.search_issues",
    {"jql": "project = PROJ ORDER BY updated DESC"}
)

也可以通过 CLI 直接调用：

python -m jira_ai.cli jira.search_issues "{\"jql\":\"project = PROJ\"}"

启动 HTTP 服务

python -m jira_ai.http_cli --host 127.0.0.1 --port 8765

如需显式指定审计日志文件：

python -m jira_ai.http_cli --audit-file logs/audit.jsonl

所有审计事件在落盘前都会对 password、token、authorization 等常见敏感字段做递归脱敏。

示例：

curl http://127.0.0.1:8765/tools
curl -X POST http://127.0.0.1:8765/invoke/jira.search_issues ^
  -H "Content-Type: application/json" ^
  -d "{\"jql\":\"project = PROJ\"}"

受控写入

当前第一条写操作是：

  • jira.add_comment

  • jira.add_review_summary_comment

  • jira.transition_issue

它要求显式审批：

python -m jira_ai.cli jira.add_comment "{\"issue_key\":\"PROJ-123\",\"body\":\"已完成评审\"}" --approved

HTTP 调用时也必须显式带上：

X-Approved: true

否则 dispatcher 会返回 APPROVAL_REQUIRED，不会真正写入 Jira。

jira.transition_issue 还会先读取当前任务可执行的 transition； 只有当你请求的流转名称真实存在于当前工作流中时，才会继续执行。

jira.update_issue_fields 则只允许更新配置白名单中的字段。默认白名单：

{
  "write_policy": {
    "allowed_issue_fields": ["labels", "components"]
  }
}

如果请求里包含未授权字段，会返回 FIELD_NOT_ALLOWED，不会向 Jira 发起修改。

如果你希望把“评审摘要 + 可选流转”一次完成，可以使用：

{
  "issue_key": "PROJ-123",
  "summary": "修复了患者检索逻辑",
  "verdict": "approved",
  "transition_name": "提交测试"
}

对应工具：

  • jira.sync_review_outcome

IDE 助手对接

如果评审和提交代码发生在 IDE 助手中，推荐直接调用：

  • jira.ide_sync_review_outcome

输入示例：

{
  "issue_key": "PROJ-123",
  "review_summary": "修复患者检索逻辑，并补充空值保护。",
  "verdict": "approved",
  "findings": ["未发现阻塞性问题"],
  "tests": ["单元测试通过"],
  "commit_sha": "abc123",
  "commit_message": "fix: 修复患者检索逻辑",
  "branch_name": "feature/patient-search",
  "review_url": "https://example/reviews/42",
  "transition_name": "提交测试"
}

该工具会先把 IDE 侧信息归一化，再复用内部的评审同步流程。

例如，代码评审摘要可以这样写回：

{
  "issue_key": "PROJ-123",
  "summary": "修复了患者检索逻辑，并补充了空值保护。",
  "verdict": "approved",
  "findings": ["未发现阻塞性问题"],
  "tests": ["已通过单元测试"],
  "links": ["PR #42"]
}

设计原则

  • 核心能力与插件外壳分离

  • Jira 原始 JSON 与内部领域模型分离

  • 写操作能力以后按显式权限和审批边界扩展

多宿主适配

项目不把能力写死在单一模型产品上，而是采用：

统一能力内核 + 宿主无关工具目录 + 薄适配层

相关文档：

  • docs/plugin-architecture.md

  • docs/integrations/codex.md

  • docs/integrations/mcp.md

  • docs/integrations/cursor.md

  • docs/integrations/github-copilot.md

MCP server

当前已提供可运行的 stdio MCP server：

python -m jira_ai.mcp_stdio

它支持：

  • initialize

  • ping

  • tools/list

  • tools/call

Codex 插件包

当前仓库已经具备 repo-local Codex 插件包结构：

  • plugins/jira-ai-codex/.codex-plugin/plugin.json

  • plugins/jira-ai-codex/.mcp.json

  • .agents/plugins/marketplace.json

安装与发布说明：

  • plugins/jira-ai-codex/INSTALL.md

  • docs/codex-plugin-release-checklist.md

Cursor 插件包

当前仓库已经具备 repo-local Cursor 插件包结构：

  • plugins/jira-ai-cursor/.cursor-plugin/plugin.json

  • plugins/jira-ai-cursor/mcp.json

  • .cursor-plugin/marketplace.json

构建与安装：

.\scripts\build-plugin.ps1 -PluginName jira-ai-cursor
.\plugins\jira-ai-cursor\scripts\doctor.ps1

然后执行本地安装脚本并重启 Cursor：

.\plugins\jira-ai-cursor\scripts\install-local.ps1

插件会注册到 %USERPROFILE%\.cursor\plugins\local\，不会出现在 Plugins 市场列表；请在 Settings → MCP 与 Rules 中确认已加载。

安装与发布说明：

  • plugins/jira-ai-cursor/INSTALL.md

  • docs/integrations/cursor.md

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • MCP Jira

    amruthabesto28
    A
    license
    -
    quality
    D
    maintenance
    Enables AI assistants to interact with Jira Cloud and Server/Data Center deployments for issue management, project tracking, and workflow automation. Supports multiple authentication methods including API tokens, OAuth 2.0, and personal access tokens.
    MIT

  • jira-mcp-server

    BillNobill
    A
    license
    B
    quality
    C
    maintenance
    Enables AI agents to manage Jira projects and issues using natural language, including creating, updating, searching issues, managing sprints, and more via the Jira API.
    36
    55
    1
    MIT

  • Jira MCP Server

    guhcostan
    A
    license
    -
    quality
    D
    maintenance
    Enables AI assistants to interact with Jira instances via the Model Context Protocol, providing 36 tools for reading and writing issues, projects, sprints, metrics, and more.
    234
    2
    MIT

View all related MCP servers

Related MCP Connectors

  • Kelvia

    Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.

  • Atlassian Rovo MCP Server

    Connect to Atlassian Jira, Confluence, and Compass to search, create, and manage your work.

  • Hexis

    Git-backed platform for skills, tools, and context for AI agents

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/JustWang1110/jira-toolkit'

If you have feedback or need assistance with the MCP directory API, please join our Discord server