# Jira MCP

A small local Model Context Protocol server for Jira Cloud. It provides four read tools by default and three deliberately guarded write tools when writes are enabled before launch.

## Tools

Read-only tools:

- `get_issue`: retrieve one issue by key or numeric ID; description is opt-in and capped at 8,000 characters.
- `search_issues`: run JQL with a default page size of 20 and a hard maximum of 50.
- `list_project_issues`: construct bounded JQL from a project key and optional status or assignee filter.
- `list_issue_transitions`: list the workflow transitions currently available for an issue, including destination status and whether a transition screen is present.

Every tool returns structured content plus a concise text view. Jira-sourced text is explicitly marked as untrusted reference data.

Write tools, available only with `JIRA_ENABLE_WRITES=true`:

- `create_issue`: create one basic issue using project, issue type, summary, optional plain-text description, and optional labels.
- `add_comment`: add one plain-text comment to an issue.
- `transition_issue`: apply one approved workflow transition by transition ID, then read the issue back to verify its resulting status.

Write inputs are length-limited and converted to Jira Cloud's Atlassian Document Format where required. The write tools support standard fields only; they do not discover or guess required custom fields or transition-screen values.

## Safety defaults

- Jira credentials are supplied through environment variables and are never committed.
- Jira text is returned as untrusted reference data, not as instructions.
- Descriptions are excluded by default and capped when explicitly requested.
- Write tools are absent unless the server starts with `JIRA_ENABLE_WRITES=true`.
- Write tools are marked destructive and non-idempotent for MCP hosts. Their descriptions require the host to show the exact proposed change and obtain human approval before calling them.
- The server never retries a write automatically. If a timeout or connection failure makes the result uncertain, check Jira before deciding whether to retry.
- Jira status is changed through workflow transitions, not by editing the status field. Call `list_issue_transitions` first, present the exact issue, transition, and destination status for approval, then pass the selected numeric transition ID to `transition_issue`.

## Requirements

- Node.js 20 or newer
- A Jira Cloud site
- An Atlassian account email and API token for live use

## Development

```bash
npm install
npm run verify
```

The verification command runs strict type-checking, a clean build, mocked Jira-client tests, in-memory MCP tests, and a compiled stdio subprocess test. Automated tests do not require Jira credentials or network access.

## Configuration

Use `.env.example` only as a reference. Supply real values through your MCP host's local environment configuration:

```text
JIRA_BASE_URL=https://your-site.atlassian.net
JIRA_EMAIL=your-atlassian-email@example.com
JIRA_API_TOKEN=your-local-api-token
JIRA_ENABLE_WRITES=false
NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem
```

Do not commit these values or paste the API token into chat. The base URL must be an HTTPS `*.atlassian.net` origin without a path, custom port, query string, or fragment.

Keep `JIRA_ENABLE_WRITES=false` for normal read-only use. To make write tools discoverable, set it to exactly `true` and restart the MCP server. Enabling the flag does not itself prove human approval; the MCP host remains responsible for approval of each exact change.

After running `npm run build`, an MCP host should launch:

```text
node /absolute/path/to/jira-mcp/dist/index.js
```

The host must pass these environment variables to the process. `NODE_EXTRA_CA_CERTS` ensures a GUI-launched Node process uses macOS's maintained certificate bundle even when it does not inherit `~/.zshenv`. Diagnostics go to stderr; stdout is reserved for the MCP protocol.

## Pagination

Search tools return `nextPageToken` and `hasMore`. Pass the token into a subsequent call to retrieve the next Jira page. The server never downloads every page automatically.

## Known boundaries

- Jira Cloud only; Jira Data Center is not supported.
- Basic authentication uses an Atlassian email and API token for this local single-user project.
- OAuth, remote HTTP hosting, custom fields, transition-screen fields, attachments, and bulk operations are outside the MVP.
- Issue creation works only where Jira accepts the standard fields exposed by this POC. Jira validation errors are returned without guessing missing custom-field values.
- Jira descriptions may contain instruction-like text. They remain untrusted data regardless of wording.
- This POC proves Jira-side MCP capabilities for a possible larger integration. It does not connect to Pronto or implement production synchronization, mapping, deduplication, or orchestration.