first commit

2026-04-26 15:14:01 +02:00
commit 0853e1c1f4
6 changed files with 164 additions and 0 deletions
@@ -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 <user_oauth_access_token>
+```
+
+For multi-tenant deployments, per-user Jira identity can be passed via:
+```
+X-Atlassian-Cloud-Id: <user_cloud_id>
+```