# Atlassian MCP Server

An MCP (Model Context Protocol) server that connects **IntelliJ IDE** to **Confluence** and **GitHub Copilot AI**, enabling you to summarize pages, analyze architecture diagrams, review docs, and rephrase text — directly from your IDE.

## Features

| Tool | Description |
|------|-------------|
| `fetch_page` | Retrieve a Confluence page's content and list attachments |
| `search_pages` | CQL-powered search across spaces |
| `analyze_content` | AI summarization, Q&A, and gap analysis on any page |
| `digest_diagram` | Describe architecture/flow diagram images using AI vision |
| `suggest_improvements` | Review a page and get structured improvement suggestions |
| `rephrase_text` | Rephrase text for email, Slack/chat, formal docs, or bullet points |

---

## Prerequisites

- Python 3.11+
- A Confluence Cloud account with API token
- A GitHub account with a PAT (`models:read` scope) **or** GitHub Copilot Business access

---

## Quick start

### 1. Clone and install

```bash
git clone <this-repo>
cd atlassian-mcp
pip install -r requirements.txt
```

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env with your credentials
```

**.env values:**

| Variable | Description |
|----------|-------------|
| `CONFLUENCE_BASE_URL` | e.g. `https://yourorg.atlassian.net/wiki` |
| `CONFLUENCE_EMAIL` | Your Atlassian account email |
| `CONFLUENCE_API_TOKEN` | Create at https://id.atlassian.com/manage-profile/security/api-tokens |
| `GITHUB_TOKEN` | PAT with `models:read` scope, or Copilot token |

### 3. Run the server

```bash
python main.py
```

Server starts at `http://localhost:8080/sse`

Health check: `http://localhost:8080/health`

---

## Connect IntelliJ

1. Open **Settings → Tools → AI Assistant → MCP Servers**
2. Click **+** and add:

```json
{
  "mcpServers": {
    "atlassian": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}
```

3. All 6 tools will appear in the AI Assistant tool window.

---

## Usage examples

Once connected, use natural language in the IntelliJ AI Assistant:

```
Fetch Confluence page 12345678
```
```
Search for pages about "authentication" in space ENG
```
```
Analyze page 12345678 — what decisions were made?
```
```
Describe the diagrams on page 12345678
```
```
What improvements can be made to page 12345678?
```
```
Rephrase this for a Slack message: "The deployment was unsuccessful 
due to a configuration mismatch in the production environment."
```

### `rephrase_text` style options

| Style | Use case |
|-------|----------|
| `email` | Professional email (default) |
| `chat` | Short Slack / Teams message |
| `formal` | Executive or client-facing communication |
| `bullet_points` | Convert prose to structured bullets |
| `summary` | Shorten to 2-3 sentences |

---

## GitHub Token setup

**Option A — GitHub Models (free tier):**
1. Go to github.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Create token with `models:read` permission
3. Use endpoint: `https://models.inference.ai.azure.com` (default in `copilot_client.py`)

**Option B — Copilot Business/Enterprise:**
Change `base_url` in `tools/copilot_client.py`:
```python
base_url="https://api.githubcopilot.com",
```

---

## Project structure

```
atlassian-mcp/
├── main.py                  # SSE server entrypoint (uvicorn + Starlette)
├── config.py                # Pydantic settings (reads .env)
├── requirements.txt
├── .env.example
├── README.md
└── tools/
    ├── __init__.py
    ├── confluence.py        # Confluence REST API client
    ├── copilot_client.py    # GitHub Copilot / OpenAI-compatible AI client
    └── tools.py             # All 6 MCP tool definitions
```

---

## Troubleshooting

**`401 Unauthorized` from Confluence**
- Check `CONFLUENCE_EMAIL` and `CONFLUENCE_API_TOKEN` in `.env`
- Token must be an API token, not your password

**`401` from GitHub Models**
- Ensure your PAT has `models:read` scope
- Try regenerating the token

**IntelliJ can't connect**
- Make sure the server is running (`python main.py`)
- Check the SSE URL matches: `http://localhost:8080/sse`
- Disable any VPN or firewall blocking localhost

**Diagrams not found**
- Diagrams must be file attachments on the page (not Draw.io macros embedded in the page body)
- Check the page in Confluence → Attachments tab