Stéphane Tailland
73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
# 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`.
|