Jira Local MCP

当前版本：3.0.0。

Jira Local MCP 是面向 Jira Server/Data Center 的本地 STDIO MCP 安全网关。Jira 只读工具立即查询；*_append 工具创建不可编辑的 operation，必须由用户在 127.0.0.1 本地审核页提交后，才会被后台串行 worker 执行。Agent 还可以查询本地队列与执行状态，并撤回尚未提交的 queued 操作。

安全边界

• MCP 不暴露提交、执行、人工对账或 Jira 删除能力；撤回只影响本地 queued 操作。

• POST /api/queue/submit 是唯一人工授权入口；worker 只消费由该接口原子写入 staging 的 operation。

• 审核页使用一次性 bootstrap 和 HttpOnly、SameSite=Strict 会话。单个会话凭据有效 15 分钟；活动页面在凭据剩余不超过 60 秒时通过受保护请求滚动换发，高风险选择仍必须二次确认。

• 操作在入队和 Jira 调用前均经过 allowlist 与删除语义检查。

• Jira 写调用由进程内及跨进程全局锁串行化。

• 重启遗留的 executing 转为 indeterminate，不会自动重试；后续 operation 转为 held，等待人工处置。

• Jira 内容是不可执行的业务数据；页面只使用安全 DOM API 渲染。

Related MCP server: jira-full-mcp

生命周期与持久化

MCP append → queued → Web submit → staged → executing → success/warning/failed history
                              └→ dependency_failed（依赖生产者失败，未调用 Jira）
                                              └→ indeterminate → 人工对账
                                                    └→ 后序 held

• data/operations.sqlite3：实时队列、队列事件、staging、执行记录和 revisions。

• data/mcp_logs.sqlite3：Tool 调用、Resource 读取和 Prompt/Skill 获取的完整业务请求/响应；不记录能力列表等协议元数据。

• SQLite 是唯一业务状态源；使用 WAL、synchronous=FULL、外键、busy timeout 和 schema version。完整 schema 初始化按进程和数据库路径执行一次，普通连接不重复获取 schema 写锁。

• queue、staging 和 history 都保存自包含的 operation 快照。主目标保存在顶层 issue_key，仅 add_issuelink 使用可空的顶层 target_issue_key；payload_json 只保存 operation 专属参数，不重复保存这两个 Key。

• description 文件会在入队时读取为 UTF-8 字符串快照，后续审核和执行不再依赖源文件；附件仍保存本地绝对路径并在执行时读取。

• 开发阶段任何数据库结构变更都要求清除对应旧库后从零构建，不迁移或兼容旧数据。3.0.0 使用 operations schema 3；不兼容旧库即使为空也拒绝打开。升级前先停止访问该库的所有 MCP、Web 和 worker 进程，再仅清除配置指向的 operations.sqlite3 及精确匹配的 operations.sqlite3-wal、operations.sqlite3-shm 文件，重新启动后创建新库。MCP 日志库结构未变，无需清理；以后其结构变更时同样清库重建。

队列不保存布局或位置。每次读取时都会按确定性规则自动分组和排序：真实 Jira 组按 Key 自然排序，待创建事务组随后按生产者创建时间排序，组内按生产者、标准字段、自定义字段、工作流、附件、评论、worklog、其他类别以及创建时间和 operation ID 排序，零散项最后展示。生产者返回真实 Key 后，下一次读取会自动重新分组；待审队列不提供任何人工排序或锚点。提交后持久化的 stage_order 仍代表用户已授权的执行顺序。

MCP 能力

• 5 个只读工具：事务、评论、工作日志、附件、JQL。

• 11 个 *_append 公开工具：10 个支持入队，移动工具立即拒绝且不入队。创建/类型变更/流转使用 ID 参数。

• jira_show_queue：打开审核页，不返回 URL 或会话凭据。

• jira_get_execution_log：读取实际执行和人工对账历史。

• jira_list_queue(page=1, page_size=50)：分页读取待审核概览，不包含 payload。

• jira_get_queue_operations(operation_ids)：按请求顺序读取 1–200 个 ID 的完整公开记录；缺失 ID 单独返回，不推断去向。

• jira_list_execution_state(page=1, page_size=50)：按执行顺序读取 staged、executing、indeterminate、held 的概览和执行元数据，不包含 payload。

• jira_cancel_queue_operations(operation_ids, expected_queue_revision)：原子撤回 1–1000 个 queued 操作，显式范围须覆盖全部直接及间接依赖。

• 4 个 Resources 和 4 个 Prompts。

与 Agent 协作审查

先用 jira_list_queue 定位条目，再按 ID 查询详情，让 Agent 根据实际内容解释或准备修正。两个清单接口每页最多 200 条，返回 items、total、page、page_size 和 revisions；各次请求是当前快照，相关 revision 改变后不能把不同页当成同一时刻的完整清单。概览只选择已有字段，详情保留完整正文及现有依赖信息，均继续脱敏。

撤回时传入查询结果中的 revisions.queue。依赖范围不完整会返回 dependency_scope_incomplete、完整的 affected_operation_ids 和缺少的 missing_operation_ids，整批保持不变；明确影响后提交完整范围。revision 冲突或任一 ID 已离开队列也会整批失败，应重新读取并核实范围，不自动重试。撤回不影响已提交或执行中的条目。

修正通过“读取详情 → 取消旧操作 → 使用现有 append 工具重新入队”完成，依赖链使用新 ID 重建；两步不原子，重新入队失败时旧操作已经撤回。新操作仍须人工 Web 审核提交。执行状态清单中消失不代表成功，实际结果请查 jira_get_execution_log。

在 Web 页面取消操作时，如果还有依赖项未选中，页面会展示完整取消范围，标记“原先选择”和“新增依赖”，列出操作 ID、说明和关联事务。点击“确认取消全部 N 项”即可，无需逐项补勾；“返回”或 Escape 放弃本次取消。确认期间页面仍会刷新，但确认范围保持不变；若队列已更新，取消会被拒绝并提示重新核对。展示记录不完整或完整范围超过 1000 项时，页面不会发送第二次取消请求；会话失效会关闭确认框。

jira_issue_move_append 保留公开签名，立即返回“不支持且未入队”。创建或克隆 Tool 返回的 operation ID 可直接作为后续修改的 issue_key，add_issuelink.target_issue_key 也支持相同引用；服务端会在生产者成功后原子物化两个顶层 Key。附件上传 operation ID 可在同一事务的 description、comment 和 worklog 中写成 [^{{attachment:op-…}}] 或 !{{attachment:op-…}}!；上传成功后，系统使用 Jira 返回的附件 ID 确认身份，并把引用原子替换为最终文件名。创建事务的初始 description 不允许附件引用，应采用“创建 → 上传 → 更新 description”。克隆来源仍必须是真实 Jira Key，也不接受自定义 placeholder。公共输出统一使用 dependency_states 表达两类依赖：键为依赖 operation ID，值为生命周期状态（未知为 unknown）；映射键顺序不代表执行顺序。

配置与运行

要求 Python 3.10+。请先进入项目目录，并在你自己的 Python 环境中执行：

python -m pip install -r requirements.txt
python -m playwright install chromium
Copy-Item config.example.yaml config.yaml
python -m pytest tests/ -q
python server.py

server.py 是 STDIO 服务，会等待 JSON-RPC 输入。Web 服务在 jira_show_queue 首次调用时延迟启动。stdout 只用于 MCP；运行日志只写脱敏 stderr。

业务 Tool 位于 core/mcp_tools/ 子包，按 Jira 查询、Jira 入队、本地队列及执行记录分模块，由 server 统一注册；审核页面入口、Prompt 和 Resource 保留在 server。本地状态查询按需读取：队列概览保留全局排序，详情按 ID 批量读取，活动执行状态在数据库中分页；每次请求的数据及 revisions 来自同一读事务。

接入支持 STDIO MCP 的通用 Agent 工具时，可使用下面的 JSON 配置。将 <JIRA_LOCAL_MCP_PROJECT_DIRECTORY> 替换为你克隆本项目后的目录；如果 Agent 配置不支持 cwd，请改为在项目目录中启动 Agent，或按该 Agent 的配置格式为 server.py 指定项目路径。

{
  "mcpServers": {
    "jira-local": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "<JIRA_LOCAL_MCP_PROJECT_DIRECTORY>"
    }
  }
}

Web API

所有 API 仅接受有效浏览器会话。页面、API 和 ETag 304 都参与滚动续期；旧会话 ID 不延长，只在自身原到期时间前继续容忍并发在途请求。停止请求后，最后一个有效凭据最多再存活 15 分钟；首次收到 403 后，页面会停止轮询、禁用审核控件并提示重新调用 jira_show_queue：

• GET /api/state：队列、执行区和 revisions，支持 ETag/304。

• POST /api/queue/cancel、POST /api/queue/submit；待审队列完全自动排序，不提供 reorder API。

• cancel 请求只接受 operation_ids 与 expected_queue_revision，不再接受 cascade_confirmed。页面确认依赖范围后重发完整 ID 列表并沿用首次请求 revision；与 MCP 共用依赖校验和取消事务。本次变更不修改数据库 schema。

• POST /api/execution/indeterminate/resolve、/held/resolve；不确定的附件上传标记为已生效时，前者要求通过 attachment: {id, filename} 提供已确认附件身份，返回 attachment_results 数组。

• GET /api/execution-history：UTC 时间范围和分页。

审核页面静态资源全部本地化，并启用 CSP、frame 防护、nosniff、no-referrer 和 no-store。

已知边界

附件目前仍只保存本地路径，没有 staging 或 hash 绑定；审核后文件可能变化。description 文件已在入队时保存内容快照。克隆源和最终规范化 Jira payload 也尚未与审核内容不可变绑定。SQLite 和本地日志不是针对同一 OS 用户恶意篡改的安全存储，因此不要宣称“生产安全”或“完整不可抵赖审计”。

3.0 元数据与执行契约

新增 11 个只读 Tool：jira_meta_server_settings、jira_meta_user、jira_meta_search_users、jira_meta_search_assignable_users、jira_meta_projects、jira_meta_issue_types、jira_meta_issue_transitions、jira_meta_fields、jira_meta_field、jira_meta_link_types、jira_meta_permissions。工具适配位于 core/mcp_tools/jira_metadata.py，读取与投影位于 core/jira_metadata.py，不缓存跨请求元数据。

查询按创建（project_key + issue_type_id）、编辑（真实 issue_key）、流转（真实 issue_key + transition_id）限定上下文。字段先摘要再详情，小型级联一次返回；大候选集分页保留归属。项目/用户默认 20，摘要默认 50，最多 100；返回预算 32 KiB。创建字段的分页游标按源位置续读，过滤后空页不表示结束。Jira 错误保留 HTTP 状态和正文并脱敏，本地/SDK/传输错误区分来源。

字段限定用户搜索尚未证实实例过滤语义时明确返回能力限制；不会以普通搜索结果宣称该字段可选。server_settings 的 features 仅返回链接和子任务功能开关。issue_types 的 create 是凭证可见创建元数据，configured 是项目配置，两者不能互相替代。

创建参数 issue_type_id、类型变更 target_issue_type_id、流转 transition_id 都直接使用 ID，不兼容旧名称参数。流转执行前复查 ID 可用性。类型映射不得覆盖 issuetype。

工时 started 接受带时区 ISO 字符串，入队校验、worker 转为 datetime。adjust_estimate 默认 auto；leave 保持估算；new 必须带 new_estimate，manual 必须带 reduce_by；两个配套值互斥，auto/leave 禁止携带。所有估算模式均按低风险处理。

克隆 field_overrides 可补齐创建字段，但禁止覆盖 project、issuetype、summary；description 复用文件快照，禁止初始附件引用。clone_subtasks=true 提前拒绝。附件使用可 seek 的二进制对象复制，首个失败后停止。warning 表示新事务主体已创建但附件处理异常，原子保存新 Key 与统一 attachment_results 列表，保留请求文件名、源附件 ID、已确认身份及成功/失败/结果未知/未尝试明细。warning 仍解析新事务引用并放行后续修改，但不自动重放整个克隆；附件占位符仍只接受单附件上传 operation ID，不从克隆结果列表推测附件。中断和落库失败仍走 indeterminate/held。

本 MCP 不提供本地文件查询工具；Agent 自行取得文件属性，MCP 保留入队/执行边界校验。真实 Jira 验证严格限于读取，写路径以 Mock 和离线 SDK 请求检查覆盖。依赖要求 jira>=3.10.5,<4。

字段限定用户搜索通过固定 groupuserpicker 取得身份建议，候选过滤标记 candidate_validation=unverified；端点可达或返回用户不证明实例过滤生效，不得据此宣称字段合法可选。该建议无 offset 续页，应缩小 query。

普通附件上传成功、失败或结果未知均记录统一附件明细；单独上传未确认成功时整体为 failed，不放行附件依赖且不自动重试。执行历史与 MCP 执行日志查询使用 attachment_results 数组；请求文件名不代替 Jira 最终文件名。请求文件名必须为非空白文本，不得包含 NUL，且不超过 1024 个字符；入队和执行前复用同一模型约束校验。