# PM Backlog — Jira MCP Server

This project runs the [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP server as a Docker container, connecting Claude Code to Jira Cloud.

## Architecture

```
Claude Code  →  HTTP (localhost:9000/mcp)  →  Docker (mcp-atlassian)  →  Jira Cloud
```

Transport: **streamable-http** (persistent process, independent of Claude Code sessions).

## Key files

- `compose/docker-compose.yml` — defines the `mcp-atlassian` container (image `ghcr.io/sooperset/mcp-atlassian:latest`, port 9000)
- `k8s/` — Kubernetes manifests (namespace `mcp`, secret, deployment, service)
- `.env` — Jira credentials (`JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`); never commit this file
- `.mcp.json` — tells Claude Code to connect to `http://localhost:9000/mcp`; auto-loaded when Claude Code opens this directory

## Common commands

```bash
docker compose -f compose/docker-compose.yml up -d          # start the server
docker compose -f compose/docker-compose.yml down           # stop the server
docker compose -f compose/docker-compose.yml logs -f        # tail logs
docker compose -f compose/docker-compose.yml pull && docker compose -f compose/docker-compose.yml up -d  # update to latest image
```

## Credentials

Credentials live in `.env` (already in `.gitignore`). Required variables:

| Variable | Description |
|---|---|
| `JIRA_URL` | Jira Cloud base URL, e.g. `https://your-org.atlassian.net` |
| `JIRA_USERNAME` | Atlassian account email |
| `JIRA_API_TOKEN` | Atlassian API token — generate at id.atlassian.com |

## Kubernetes deployment

```bash
# 1. Create the secret from .env
kubectl create secret generic mcp-jira-credentials -n mcp \
  --from-literal=JIRA_URL="$(grep JIRA_URL .env | cut -d= -f2-)" \
  --from-literal=JIRA_USERNAME="$(grep JIRA_USERNAME .env | cut -d= -f2-)" \
  --from-literal=JIRA_API_TOKEN="$(grep JIRA_API_TOKEN .env | cut -d= -f2-)" \
  --dry-run=client -o yaml | kubectl apply -f -

# 2. Apply all manifests
kubectl apply -f k8s/

# 3. Access locally via port-forward
kubectl port-forward -n mcp svc/mcp-jira 9000:9000
```

## MCP tools

Once the server is running and Claude Code is connected, Jira tools are available directly in this session (search issues, create/update tickets, etc.). The MCP server exposes the full mcp-atlassian tool surface.

## Coding Guidelines

- **Language**: all code, comments, commit messages, and documentation in English.
- **Comments**: only when the why is non-obvious. No block comments, no section dividers.
- **Conciseness**: no boilerplate, no placeholders, no "coming soon" stubs.
- **No over-engineering**: solve the problem at hand; don't design for hypothetical futures.
- **Images**: always use `latest` when the tag exists; pin to the latest known version only when `latest` is not published (e.g. Harbor). Keeps images up to date with security patches.

## OAuth2 (future)

The image has built-in OAuth2 proxy support. To enable it:
1. Uncomment `ATLASSIAN_OAUTH_*` variables in `.env` and fill in credentials from the [Atlassian developer console](https://developer.atlassian.com/console/myapps/).
2. Put a reverse proxy (nginx/Caddy) in front of port 9000 to enforce bearer token validation before forwarding to `/mcp`.