# PurpleTrack — JiraMock

A self-hosted Jira clone designed for testing MCP (Model Context Protocol) integrations on Azure. Ships with a REST API, MCP server, and purple web frontend — all in Docker.

---

## 🚀 Quick Start (Azure VM)

```bash
# 1. Clone the repo on your VM
git clone https://github.com/YOUR_ORG/jira-clone.git
cd jira-clone

# 2. Build and launch
docker compose up -d --build

# 3. Access
#   Frontend:  http://<VM_IP>:3000
#   API:       http://<VM_IP>:8000
#   API Docs:  http://<VM_IP>:8000/docs
```

> **Azure NSG**: Open inbound ports **3000** (frontend) and **8000** (API) in your Network Security Group.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│               Docker Network            │
│                                         │
│  ┌──────────┐    ┌──────────────────┐  │
│  │ Frontend │    │    Backend       │  │
│  │  nginx   │───▶│  FastAPI + JSON  │  │
│  │  :3000   │    │    DB  :8000     │  │
│  └──────────┘    └──────────────────┘  │
│                         ▲               │
│  ┌──────────────────┐   │               │
│  │   MCP Server     │───┘               │
│  │  (stdio/Python)  │                   │
│  └──────────────────┘                   │
└─────────────────────────────────────────┘
```

---

## 📡 REST API

The API mirrors Jira's REST API v3 structure. All endpoints at `/rest/api/3/`.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/rest/api/3/project` | List all projects |
| POST | `/rest/api/3/project` | Create project |
| GET | `/rest/api/3/project/{key}` | Get project |
| DELETE | `/rest/api/3/project/{key}` | Delete project |
| GET | `/rest/api/3/issue` | List/filter issues |
| POST | `/rest/api/3/issue` | Create issue |
| GET | `/rest/api/3/issue/{key}` | Get issue + comments |
| PUT | `/rest/api/3/issue/{key}` | Update issue |
| DELETE | `/rest/api/3/issue/{key}` | Delete issue |
| POST | `/rest/api/3/issue/{key}/transitions` | Move status |
| GET | `/rest/api/3/issue/{key}/comment` | List comments |
| POST | `/rest/api/3/issue/{key}/comment` | Add comment |
| GET | `/rest/api/3/search?jql=...` | JQL search |
| GET | `/rest/api/3/users` | List users |
| GET | `/rest/api/3/stats` | Dashboard stats |

Full interactive docs at `http://<host>:8000/docs`

---

## 🤖 MCP Server

### Tools Available

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects |
| `create_project` | Create a project |
| `get_project` | Get project details |
| `delete_project` | Delete a project |
| `list_issues` | List/filter issues |
| `create_issue` | Create an issue |
| `get_issue` | Get issue + comments |
| `update_issue` | Update issue fields |
| `delete_issue` | Delete an issue |
| `transition_issue` | Change issue status |
| `add_comment` | Comment on an issue |
| `list_comments` | List issue comments |
| `list_users` | List available users |
| `search_issues` | JQL search |
| `get_stats` | Dashboard statistics |

### Claude Desktop Config

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jiramock": {
      "command": "docker",
      "args": [
        "exec", "-i", "jiramock-mcp",
        "python", "server.py"
      ],
      "env": {
        "JIRA_BASE_URL": "http://backend:8000"
      }
    }
  }
}
```

### Azure AI Foundry / HTTP MCP config

If your MCP client supports HTTP transport, point it at:
```
http://<VM_IP>:8000
```
and use the REST endpoints directly, or wrap the MCP server behind an SSE/HTTP proxy.

---

## 📁 Project Structure

```
jira-clone/
├── backend/
│   ├── main.py           # FastAPI application
│   ├── requirements.txt
│   └── Dockerfile
├── mcp-server/
│   ├── server.py         # MCP server (stdio transport)
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── index.html        # Purple web UI
│   └── Dockerfile
├── nginx/
│   └── default.conf      # Reverse proxy config
├── docker-compose.yml
└── README.md
```

---

## 🔧 Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `JIRA_BASE_URL` | `http://backend:8000` | MCP server → backend URL |

Data is persisted in a Docker volume (`jiramock-data`) at `/data/db.json`.

---

## 🛑 Management

```bash
# Stop
docker compose down

# Stop and wipe data
docker compose down -v

# Logs
docker compose logs -f backend
docker compose logs -f mcp-server

# Rebuild after changes
docker compose up -d --build
```

---

## 🔁 Migrating to Real Jira

When ready to swap to real Jira:
1. Replace `JIRA_BASE_URL` with your Jira instance URL
2. Add `JIRA_API_TOKEN` and `JIRA_USER` env vars to the MCP server
3. Update `server.py` to use basic auth: `httpx.AsyncClient(auth=(user, token))`

The MCP tool interface remains identical — no changes to your Claude prompts or Azure Foundry config.