Do Jira Stuff

DoJiraStuff --通过克劳德代码对话Jira

与你的Jira板交谈，就像与队友交谈一样。 没有MCP服务器。没有中间件。没有GUI。只是Claude代码+Jira REST API。

______________________________________________________________________

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   you  ──▶  claude code  ──▶  jira rest api v3  ──▶  jira     │
│                  ▲                                              │
│                  │                                              │
│             CLAUDE.md                                           │
│          (api playbook)                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

______________________________________________________________________

这是什么

DoJiraStuff 是一个 零依赖、会话式Jira接口 基于克劳德代码构建。您不用点击UI或编写脚本，而是用简明的英语描述您想要的内容，Claude处理Jira REST API调用，解析响应，并以清晰可读的格式呈现结果。

秘方 是 CLAUDE.md --一个机器可读的剧本，与你的代码放在一起，教Claude如何进行身份验证、访问哪些端点、如何处理Atlassian文档格式（ADF）有效载荷以及陷阱是什么。

为什么不是MCP？

MCP（模型上下文协议）功能强大，但它引入了服务器进程、配置文件和外部依赖关系。这个回购故意避免了这一切。所有内容都使用您已有的工具在本地运行： curl, python3以及克劳德密码。

______________________________________________________________________

运作原理

┌──────────────────────────────────────────────────────────────────────┐
│  CONVERSATION                                                        │
│                                                                      │
│  You:    "Create a spike in PROJ about evaluating VAPI, 5 points"   │
│                                                                      │
│  Claude: 1. Reads .env for credentials                              │
│          2. Checks field metadata for PROJ/Spike issue type         │
│          3. Builds ADF-formatted payload                             │
│          4. POSTs to /rest/api/3/issue                              │
│          5. Returns: ✓ PROJ-123 created → [link]                    │
└──────────────────────────────────────────────────────────────────────┘

克劳德在整个对话中保持上下文。您可以按键、链操作（“现在将其分配给我并将其移动到正在进行中”）引用工单，并就结果提出后续问题——所有这些都不需要重述上下文。

______________________________________________________________________

先决条件

______________________________________________________________________

设置

步骤1-获取Atlassian API代币

1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 创建API令牌
3. 命名（例如。 claude-code)
4. 立即复制令牌 --你不会再看到它了

步骤2——配置您的 .env

cp .env.example .env

编辑 .env 与你的价值观：

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@yourcompany.com
JIRA_API_TOKEN=your_api_token_here
JIRA_DEFAULT_PROJECT=YOUR_PROJECT

JIRA_DEFAULT_PROJECT 这只是一种退路。您可以在请求中内联指定任何项目键，例如。 _“给我看打开的ENG门票”_ --克劳德会用它来代替。

.env 是合法的，永远不会被承诺。

步骤3--验证您的凭据

set -a && source .env && set +a
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "$JIRA_BASE_URL/rest/api/3/myself" | python3 -m json.tool

您应该以JSON格式查看您的Atlassian帐户详细信息。如果你得到401，你的代币是错误的或过期的。

步骤4——在Claude代码中打开

cd /path/to/DoJiraStuff
claude

克劳德将自动阅读 CLAUDE.md 查看其操作说明。开始说话。

______________________________________________________________________

项目结构

DoJiraStuff/
│
├── CLAUDE.md          ← The brains: API patterns, curl templates,
│                        field reference, ADF format, gotchas.
│                        Claude reads this before every operation.
│
├── README.md          ← You are here
│
├── .env               ← Your credentials (gitignored, never committed)
├── .env.example       ← Safe template — edit and copy to .env
└── .gitignore         ← Protects .env from accidental commits

的作用 CLAUDE.md

CLAUDE.md 是这个项目的核心。这不是人类的文件，而是 克劳德操作说明。它包括：

• 如何通过以下方式获取凭据 set -a
• 如何从请求中解析项目密钥与默认密钥
• curl 每个CRUD操作的模板
• Jira用于富文本字段的Atlassian文档格式（ADF）
• 如何发现任何项目的必填字段和允许值
• 如何获取和应用工作流转换
• 响应格式指南

如果添加具有不同必填字段的新项目，请更新 CLAUDE.md 克劳德将在下次会议上知道这件事。

______________________________________________________________________

你能做什么

阅读

Show me all open tickets in PROJ
What's the status of PROJ-42?
List all bugs assigned to me
Show me high priority issues in the current sprint
Search for tickets mentioning "authentication" in ENG
Give me everything that's In Progress across PROJ

创建

Create a spike in PROJ: evaluate VAPI as a dialer provider, 5 points
File a bug in ENG: login crashes on Safari, high priority
Create a story: "As a user I want to reset my password"
Add a task to PROJ about updating the API docs

更新

Move PROJ-42 to In Progress
Assign ENG-15 to me
Set PROJ-7 priority to High
Update the summary of PROJ-42 to "Fix Safari login crash"
Add acceptance criteria to PROJ-123

评论

Add a comment to PROJ-42: "Fixed in PR #123, deploying Friday"
Comment on ENG-15 that it's blocked by PROJ-9

删除

Delete PROJ-42

______________________________________________________________________

多项目支持

Claude直接从您的请求中解析项目密钥。没有单个锁定的项目。

这 JIRA_DEFAULT_PROJECT 在 .env 只是模糊请求的后备方案。

______________________________________________________________________

支持的问题类型

问题类型因Jira项目配置而异。常见类型包括：

要查看项目中可用的问题类型，请执行以下操作：

set -a && source .env && set +a
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "$JIRA_BASE_URL/rest/api/3/issue/createmeta?projectKeys=YOUR_PROJECT" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for p in data['projects']:
    for it in p['issuetypes']:
        print(it['id'], '-', it['name'])
"

______________________________________________________________________

Atlassian文档格式（ADF）

Jira的REST API v3 不接受纯字符串 用于富文本字段。所有描述、注释和验收标准值都必须使用ADF——一种JSON文档结构。

最小的ADF包装：

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Your text here." }
      ]
    }
  ]
}

克劳德会自动处理这件事。你永远不需要自己写ADF。

______________________________________________________________________

查找必填字段

每个Jira项目都可以有不同的必填字段和自定义字段ID。在新项目中创建问题之前，Claude将自动获取字段元数据。您也可以手动操作：

set -a && source .env && set +a
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Accept: application/json" \
  "$JIRA_BASE_URL/rest/api/3/issue/createmeta?projectKeys=YOUR_PROJECT&expand=projects.issuetypes.fields" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for p in data['projects']:
    for it in p['issuetypes']:
        print('\\nIssue type:', it['name'])
        for k, v in it['fields'].items():
            req = ' (REQUIRED)' if v.get('required') else ''
            vals = [str(x.get('id')) + ':' + str(x.get('value','')) for x in v.get('allowedValues', [])]
            print(' ', k, '-', v.get('name','') + req, '|', ', '.join(vals) if vals else '')
"

______________________________________________________________________

可重复性

要在新机器上从头开始设置此功能：

git clone https://github.com/YOUR_ORG/DoJiraStuff
cd DoJiraStuff
cp .env.example .env
# edit .env and add your API token
claude

就是这样。不 npm install不 pip install。无构建步骤。唯一的运行时依赖关系是 curl 和 python3，两者都预装在macOS上。

______________________________________________________________________

故障排除

______________________________________________________________________

安全

• 您的API代币有效期 仅 在 .env 在本地计算机上
• .gitignore 确保 .env 从未承诺
• 该令牌具有与Jira帐户相同的权限——将其视为密码
• 要撤销：https://id.atlassian.com/manage-profile/security/api-tokens
• 切勿将您的令牌粘贴到提示、问题或评论中 --它将出现在历史上

______________________________________________________________________

配置参考

______________________________________________________________________

*建于 克劳德代码 -由Jira REST API v3提供支持*