@thammarongg/jira-mcp 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: jira
+description: Use when the user asks about Jira work — boards, sprints, backlog, epics, issues, JQL search, creating/updating/transitions, comments, worklogs — or when the jira MCP server is not yet configured and needs setup. Covers the jira-mcp MCP server (43 tools) for Jira Cloud and Data Center.
+---
+
+# Jira (via jira-mcp MCP server)
+
+The `jira` MCP server exposes the full Jira REST API: boards, sprints,
+epics, issues (JQL, transitions, comments, worklogs), projects, users, and a
+raw `jira_api` passthrough for any `/rest/...` endpoint. Works with Jira
+Cloud (API v3) and Data Center (API v2); field-shape differences are handled
+server-side.
+
+## If the jira MCP tools are not available
+
+Tell the user the server isn't configured and offer to set it up. Required
+env vars:
+
+- `JIRA_BASE_URL` — `https://your-org.atlassian.net` (Cloud) or
+  `https://jira.yourcompany.com` (DC)
+- Cloud: `JIRA_EMAIL` + `JIRA_API_TOKEN` (token from id.atlassian.com →
+  Security → API tokens)
+- DC: `JIRA_USERNAME` + `JIRA_API_TOKEN` (PAT) or `JIRA_PASSWORD` (app password)
+
+Claude Code one-liner:
+
+```bash
+claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
+  --env JIRA_EMAIL=you@example.com --env JIRA_API_TOKEN=xxx \
+  -- npx -y @thammarongg/jira-mcp
+```
+
+opencode (`opencode.json`):
+
+```json
+{
+  "mcp": {
+    "jira": {
+      "type": "local",
+      "command": ["npx", "-y", "@thammarongg/jira-mcp"],
+      "environment": {
+        "JIRA_BASE_URL": "https://your-org.atlassian.net",
+        "JIRA_EMAIL": "you@example.com",
+        "JIRA_API_TOKEN": "xxx"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+Never print or store the API token in files, commits, or chat output.
+After setup, verify with the `get_current_user` tool.
+
+## Tool map
+
+- **Boards/sprints**: `list_boards`, `get_board`, `list_sprints`, `get_sprint`,
+  `create_sprint`, `update_sprint`, `close_sprint`, `get_sprint_issues`,
+  `get_sprint_view` (UI-like full view), `get_backlog`
+- **Epics**: `list_epics`, `get_epic`, `get_epic_issues`, `create_epic`,
+  `move_issue_to_epic`, `get_epic_meta`
+- **Issues**: `get_issue`, `create_issue`, `update_issue`, `delete_issue`,
+  `search_issues` (JQL), `get_issue_create_meta`, `get_issue_transitions`,
+  `transition_issue`, `assign_issue`, `add_comment`, `list_comments`,
+  `delete_comment`, `get_issue_worklogs`, `add_worklog`
+- **Projects/users/meta**: `list_projects`, `get_project`,
+  `get_project_components`, `create_project_component`,
+  `get_project_issue_types`, `get_project_roles`, `get_project_versions`,
+  `get_current_user`, `find_users`, `get_user`, `get_fields`, `get_issue_types`
+- **Escape hatch**: `jira_api` — raw call to any `/rest/...` endpoint
+
+## Workflows
+
+**Sprint status**: `list_boards` → pick board → `list_sprints` (state
+`active`) → `get_sprint_issues` or `get_sprint_view` for the full picture.
+
+**Backlog review**: `get_backlog(boardId)` — issues in the board's projects
+with no sprint, ordered by rank.
+
+**Create an issue**: call `get_issue_create_meta(projectKeys=...)` first to
+discover valid issue types and required fields, then `create_issue`
+(custom fields go in `customFields`, e.g. `{ "customfield_10010": "..." }`).
+
+**Move work through the workflow**: `get_issue_transitions(issueKey)` to see
+available transitions and required fields, then `transition_issue`.
+
+**Search**: `search_issues` with JQL. Common queries:
+- Current sprint: `project = PROJ AND sprint = <sprintId> ORDER BY rank`
+- Unassigned in project: `project = PROJ AND assignee IS EMPTY`
+- Due this week: `project = PROJ AND duedate <= endOfWeek() ORDER BY duedate`
+- By label: `project = PROJ AND labels in (release, critical)`
+
+## Tips
+
+- List tools paginate with `startAt`/`maxResults`; responses include `total` —
+  page with `startAt` when `total` exceeds the page size.
+- Assignees: pass an account ID on Cloud, a username on DC — the server maps
+  it to the right field shape automatically.
+- To remove an issue from an epic: `update_issue` with
+  `fields: { "epic": null }`.
+- Anything not covered by a dedicated tool → `jira_api` with method, path
+  (must stay under `/rest/`), query, body.