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.

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.

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:

"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

{
  "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

{
  "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

{
  "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

{
  "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

uv sync
uv run adins-prd-mcp

Publishing

uv build
uv publish