Metadata-Version: 2.5
Name: adins-prd-mcp
Version: 0.5.7
Summary: Custom MCP server for AdIns — Confluence read, attachment download, and docx rendering
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4==4.12.3
Requires-Dist: docxtpl==0.19.0
Requires-Dist: fastmcp==2.3.3
Requires-Dist: keyring==25.6.0
Requires-Dist: markdownify==0.14.1
Requires-Dist: mistletoe==1.4.0
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: requests==2.32.3
Description-Content-Type: text/markdown

# adins-prd-mcp

MCP server for reading Confluence PRD pages and rendering SRS/URS documents as Word files.
Built for use with AI agents in the AdIns SDLC toolchain.

## Tools

### Confluence tools

| Tool | Description |
|---|---|
| `get_confluence_page` | Fetch a page by numeric ID. Returns markdown or raw HTML in context. |
| `get_confluence_page_to_file` | Fetch a page and write content directly to a local file. Returns path and size only. |
| `search_confluence` | Search using CQL. |
| `list_confluence_attachments` | List attachments on a page. |
| `download_confluence_attachment` | Download an attachment to a local path. |
| `get_confluence_page_ancestors` | Return the ancestor chain (root → immediate parent). |
| `get_confluence_page_siblings` | Return sibling pages sharing the same parent. |

### Database tools

| Tool | Description |
|---|---|
| `init_document_db` | Create the SQLite DB and store module-level metadata. |
| `store_feature` | Parse and store one PRD feature (and its menus) into the DB. |
| `store_feature_from_file` | Same as `store_feature` but reads the payload from a local JSON file. |
| `raw_query_exec` | Execute a raw SQL statement against the DB. Read-only by default; pass `write=True` for DML/DDL. Results capped at 200 rows. |

### Render tools

| Tool | Description |
|---|---|
| `render_srs_docx` | Render an SRS Word document from the DB. |
| `render_urs_docx` | Render a URS Word document from the DB. |

---

## Workflow

```
init_document_db(db_path, meta)
  ↓
get_confluence_page_to_file(page_id, output_path)   ← subagent fetches its page to disk
  ↓
store_feature(db_path, feature_data)                ← subagent stores parsed data
  ↓ (up to 5 parallel subagents, one per feature page)
render_srs_docx(template_path, output_path, db_path)
  or
render_urs_docx(template_path, output_path, db_path)
```

The main agent sets `service_order`. Each subagent sets `feature_order` from its sibling
position in the Confluence page tree. Menu order is derived from list position.
The agent never assembles the full context dict. The render tools read directly from the DB.

---

## Requirements

- Python 3.12+
- At least one of the two auth methods configured (see below)

---

## Authentication

Two methods are supported. The `CONFLUENCE_AUTH_MODE` variable controls which
one is used. The default (`auto`) tries Basic first and falls back to OAuth
automatically.

| `CONFLUENCE_AUTH_MODE` | Behaviour |
|---|---|
| `auto` *(default)* | Uses Basic if `CONFLUENCE_EMAIL` + `CONFLUENCE_API_TOKEN` are set. Falls back to OAuth on missing vars or HTTP 401. |
| `basic` | Forces Basic auth only. Fails hard if the token vars are missing. |
| `oauth` | Forces OAuth 2.0 only. Ignores token vars entirely. |

### Option A — Basic auth (API token)

Generate a classic API token at
[id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).

Required env vars:

| Variable | Description | Example |
|---|---|---|
| `CONFLUENCE_BASE_URL` | Atlassian site URL | `https://yourcompany.atlassian.net` |
| `CONFLUENCE_EMAIL` | Account email | `you@yourcompany.com` |
| `CONFLUENCE_API_TOKEN` | Classic API token | `ATATT3x...` |

### Option B — OAuth 2.0 (3LO)

Register an OAuth 2.0 (3LO) app at
[developer.atlassian.com/console/myapps](https://developer.atlassian.com/console/myapps/).

App settings:
- **Callback URL:** `http://localhost:8877/callback`
- **Scopes required:**
  - `read:confluence-content.all`
  - `read:confluence-props`
  - `read:confluence-space.summary`
  - `search:confluence`
  - `readonly:content.attachment:confluence`
  - `offline_access` *(enables silent token refresh — check this box)*

Required env vars:

| Variable | Description | Example |
|---|---|---|
| `CONFLUENCE_BASE_URL` | Atlassian site URL | `https://yourcompany.atlassian.net` |
| `CONFLUENCE_OAUTH_CLIENT_ID` | OAuth app Client ID | `EEKB1cFP5L8Pu...` |
| `CONFLUENCE_OAUTH_CLIENT_SECRET` | OAuth app Client Secret | `ATOAxxxxxxxx` |

**First-time login:** on the first tool call that needs Confluence access, the
MCP server opens your browser to the Atlassian authorisation page. After you
approve, the server captures the callback automatically and stores tokens in
your OS credential store (Windows Credential Manager / macOS Keychain /
libsecret). Subsequent runs reuse the stored tokens and refresh them silently
— no browser interaction needed until the refresh token itself expires.

**Force re-authentication:**

```json
"env": {
  "CONFLUENCE_OAUTH_FORCE_REAUTH": "true"
}
```

Set this temporarily to clear stored tokens and trigger a fresh browser login.
Remove the flag after the new tokens are stored.

---

## Configuration

### With `uvx` (recommended) — Basic auth

```json
{
  "mcpServers": {
    "adins-prd-mcp": {
      "command": "uvx",
      "args": ["adins-prd-mcp"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_EMAIL": "you@yourcompany.com",
        "CONFLUENCE_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### With `uvx` — OAuth 2.0

```json
{
  "mcpServers": {
    "adins-prd-mcp": {
      "command": "uvx",
      "args": ["adins-prd-mcp"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_AUTH_MODE": "oauth",
        "CONFLUENCE_OAUTH_CLIENT_ID": "your-client-id",
        "CONFLUENCE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### With a local install

```json
{
  "mcpServers": {
    "adins-prd-mcp": {
      "command": "python",
      "args": ["-m", "adins_prd_mcp.server"],
      "cwd": "/path/to/mcp",
      "env": {
        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
        "CONFLUENCE_EMAIL": "you@yourcompany.com",
        "CONFLUENCE_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### All environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `CONFLUENCE_BASE_URL` | ✅ always | — | Atlassian site URL |
| `CONFLUENCE_EMAIL` | Basic auth only | — | Account email |
| `CONFLUENCE_API_TOKEN` | Basic auth only | — | Classic API token |
| `CONFLUENCE_AUTH_MODE` | ❌ | `auto` | `auto` / `basic` / `oauth` |
| `CONFLUENCE_OAUTH_CLIENT_ID` | OAuth only | — | OAuth app Client ID |
| `CONFLUENCE_OAUTH_CLIENT_SECRET` | OAuth only | — | OAuth app Client Secret |
| `CONFLUENCE_OAUTH_FORCE_REAUTH` | ❌ | `false` | Set `true` to discard stored tokens |

---

## store_feature payload shape

```json
{
  "db_path": "output/LMS-1.5.db",
  "feature_data": {
    "source_id": "935559172",
    "source_version": 24,
    "raw_content_path": "output/LMS-1.5/935559172/raw.md",
    "service_name": "Amendment",
    "service_style": "standard",
    "service_order": 0,
    "feature_name": "Partial Prepayment",
    "feature_description": "Partial Prepayment merupakan fitur ...",
    "feature_order": 2,
    "process_flow_image_path": "output/LMS-1.5/935559172/process-flow.png",
    "menus": [
      {
        "title": "Partial Prepayment Request",
        "actor": "Operation Staff",
        "description": "Menu for submitting a partial prepayment request.",
        "figma_url": "[Figma - Partial Prepayment Request](https://www.figma.com/proto/...)",
        "constraints": [
          {
            "group": "Ada beberapa persyaratan:",
            "children": [
              {"text": "Status agreement tidak sedang dalam proses lain."},
              {"text": "Belum mencapai maksimal amendment limit."}
            ]
          }
        ],
        "boundaries": [
          {"group": "", "children": [{"text": "Fitur ini belum support untuk kontrak syariah."}]}
        ],
        "actions": [
          {"action": "Submit", "description": "Submit the prepayment request for approval."}
        ],
        "scenarios": [
          {"no": "1", "scenario": "Submit with valid data.", "expectation": "Request saved with status Pending."}
        ],
        "gaps": [
          {
            "number": "GAP-001",
            "title": "Prepayment amount validation",
            "summary": "Current system does not validate prepayment amount.",
            "current_system": "No validation exists.",
            "system_solution": "Add server-side validation."
          }
        ]
      }
    ]
  }
}
```

---

## Development

```bash
uv sync
uv run adins-prd-mcp
```

## Publishing

```bash
uv build
uv publish
```
