From 0853e1c1f49cf9d28f8895ab550c566c36a09be1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Tailland?= Date: Sun, 26 Apr 2026 15:14:01 +0200 Subject: [PATCH] first commit --- .gitignore | 3 ++ .mcp.json | 8 +++++ CLAUDE.md | 54 ++++++++++++++++++++++++++++ README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 9 +++++ notes.md | 1 + 6 files changed, 164 insertions(+) create mode 100644 .gitignore create mode 100644 .mcp.json create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 docker-compose.yml create mode 100644 notes.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b2f9579 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.env +certs/ +.claude diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..2f7f171 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "mcp-atlassian": { + "type": "http", + "url": "http://localhost:9000/mcp" + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..436b816 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,54 @@ +# 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 + +- `docker-compose.yml` — defines the `mcp-atlassian` container (image `ghcr.io/sooperset/mcp-atlassian:latest`, port 9000) +- `.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 up -d # start the server +docker compose down # stop the server +docker compose logs -f # tail logs +docker compose pull && docker compose 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 | + +## 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`. diff --git a/README.md b/README.md new file mode 100644 index 0000000..2cb2859 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# PM Backlog — MCP Atlassian Setup + +This project connects Claude Code to Jira via the [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP server, running as a Docker container over streamable HTTP. + +## Architecture + +``` +Claude Code → HTTP (localhost:9000/mcp) → Docker (mcp-atlassian) → Jira Cloud +``` + +The server uses the **streamable-http** transport (not stdio), which keeps the MCP server as a persistent process independent of Claude Code sessions. + +## Prerequisites + +- Docker and Docker Compose installed +- A Jira Cloud account with an API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens)) + +## Configuration + +### Environment variables (`.env`) + +| Variable | Description | +|---|---| +| `JIRA_URL` | Your Jira Cloud base URL (e.g. `https://your-org.atlassian.net`) | +| `JIRA_USERNAME` | Your Atlassian account email | +| `JIRA_API_TOKEN` | Your Atlassian API token | + +OAuth2 variables are present but commented out — see the [OAuth2 section](#oauth2-future) below. + +### Claude Code (`.mcp.json`) + +Claude Code is configured to connect to the MCP server via: + +```json +{ + "mcpServers": { + "mcp-atlassian": { + "url": "http://localhost:9000/mcp" + } + } +} +``` + +This file is picked up automatically when Claude Code is opened in this directory. + +## Running the server + +**Start:** +```bash +docker compose up -d +``` + +**Stop:** +```bash +docker compose down +``` + +**View logs:** +```bash +docker compose logs -f +``` + +**Update to the latest image:** +```bash +docker compose pull && docker compose up -d +``` + +The server listens on `http://localhost:9000/mcp`. + +## OAuth2 (future) + +The mcp-atlassian server has built-in OAuth2 proxy support. When you are ready to enable it: + +1. Uncomment the `ATLASSIAN_OAUTH_*` variables in `.env` and fill in your OAuth2 app credentials (created in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/)). +2. The server will expose standard OAuth2 discovery and token endpoints: + - `GET /.well-known/oauth-authorization-server` + - `POST /oauth/token` + - `POST /oauth/register` +3. Place a reverse proxy (nginx, Caddy, etc.) in front of port 9000 to enforce bearer token validation before forwarding requests to `/mcp`. + +Clients then authenticate with: +``` +Authorization: Bearer +``` + +For multi-tenant deployments, per-user Jira identity can be passed via: +``` +X-Atlassian-Cloud-Id: +``` diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..d6f0b9a --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,9 @@ +services: + mcp-atlassian: + image: ghcr.io/sooperset/mcp-atlassian:latest + ports: + - "9000:9000" + env_file: + - .env + command: ["--transport", "streamable-http", "--port", "9000"] + restart: unless-stopped diff --git a/notes.md b/notes.md new file mode 100644 index 0000000..ad05b18 --- /dev/null +++ b/notes.md @@ -0,0 +1 @@ +JIRA MCP Server: https://github.com/sooperset/mcp-atlassian