confluence-markdown 0.1.0__tar.gz

confluence_markdown-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,52 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+## Description
+
+<!-- Brief description of the bug -->
+
+## Steps to Reproduce
+
+```bash
+# Command that triggers the bug
+confluence-markdown --action ...
+```
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+## Actual Behavior
+
+<!-- What happens instead? Paste the error message below -->
+
+```
+error message here
+```
+
+## Environment
+
+- OS:
+- Python version: (`python --version`)
+- Tool version: (`confluence-markdown --version`)
+- Confluence Data Center version:
+
+## Verbose Output
+
+<!-- Run with `--verbose` and paste the output below. Redact any credentials. -->
+
+<details>
+<summary>Verbose log</summary>
+
+```
+confluence-markdown --verbose --action ...
+```
+
+</details>

confluence_markdown-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature Request
+about: Suggest a new feature
+labels: enhancement
+---
+
+## Summary
+
+<!-- Brief description of the requested feature -->
+
+## Problem / Motivation
+
+<!-- What problem does this feature solve? -->
+
+## Proposed Solution
+
+<!-- How should it work? Example usage: -->
+
+```bash
+confluence-markdown --action ...
+```
+
+## Alternatives Considered
+
+<!-- Have you considered other approaches? -->
+
+## Additional Context
+
+<!-- Screenshots, links, related issues -->

confluence_markdown-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## Description
+
+<!-- What was changed and why? -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring (no functional changes)
+- [ ] Documentation
+- [ ] Other
+
+## Checklist
+
+- [ ] `uv run ruff check src/` — no errors
+- [ ] `uv run pytest` — all tests pass
+- [ ] CHANGELOG.md updated
+- [ ] Documentation updated (if applicable)

confluence_markdown-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build docs
+        run: uv run mkdocs build --strict

confluence_markdown-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

confluence_markdown-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release to PyPI and GitHub
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Build package
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          body_path: RELEASE_NOTES.md
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

confluence_markdown-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing and coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.tox/
+
+# Test files
+test-*.md
+
+# IDE and editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Claude Code
+.claude/
+
+# Agent and LLM configuration (kept out of version control)
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.codex/
+.cursor/
+.cursorrules
+.windsurfrules
+.aider*
+.gemini/
+.antigravity/
+.junie/
+.mcp.json
+
+# MkDocs build output
+site/
+
+# Internal work plans / implementation prompts (kept out of version control)
+.plan/
+
+# One-off scripts with credentials
+add_*.py
+create_*.py
+setup_*.py
+fix_*.py
+update_*.py
+convert_*.py

confluence_markdown-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

confluence_markdown-0.1.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased] - 2026-06-22
+
+### Added
+
+#### Confluence storage format (XHTML) mode
+
+Support for Confluence **storage format** (Atlassian's official format), the
+lossless XHTML representation used by Confluence's REST API
+(`representation: "storage"`). Unlike Markdown, storage format is a pure
+passthrough: tables with colspan/rowspan, macros (`ac:` elements), layouts,
+and all Confluence-specific constructs are preserved exactly.
+
+See the [Confluence storage format documentation](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html).
+
+**MCP server — new `*_storage` tool family (recommended for agents):**
+- `get_page_storage` — returns raw storage XHTML (pretty-printed); use as input for the other storage write tools.
+- `edit_page_storage` — replaces page body with storage XHTML; validates well-formedness before upload.
+- `create_page_storage` — creates a new page with storage XHTML content.
+- `add_content_storage` — appends/prepends storage XHTML to an existing page.
+
+All storage write tools preserve the human-in-the-loop elicitation confirmation.
+
+**New diagnostic tool:** `check_elicitation_support` — returns
+`{"elicitation_supported": true/false}` so you can verify at runtime
+whether the connected MCP client will trigger the write confirmation prompt.
+
+The MCP server `instructions` now steer agents toward the `*_storage` tools as
+the preferred choice for content operations.
+
+**New MCP resource:** `confluence://page/{page_id}/storage` — exposes raw
+storage XHTML as an MCP resource.
+
+**CLI:** `--format {md,storage}` flag (default `md`) for `download` and `edit`
+actions. `--format storage` downloads/edits pages in Confluence storage format
+(XHTML, Atlassian's official format) without any Markdown conversion.
+
+**New helpers in `ConfluenceClient`:**
+- `_validate_storage_xhtml(html)` — validates well-formedness, normalises `<br>` and void elements, detects bare `&`; rejects malformed input locally before the API call.
+- `_prettify_storage(html)` — pretty-prints storage XHTML while preserving significant whitespace in `<pre>`, `<ac:plain-text-body>`, and `<ac:plain-text-link-body>`.
+
+### Fixed
+
+- `edit_page_with_editor` with `content_type="html"` (non-interactive mode)
+  previously converted storage XHTML to Markdown and back (`html→md→html`),
+  silently destroying tables and macros. It now validates and uploads the
+  storage XHTML directly.
+
+### Breaking Changes
+
+The following MCP tool names have been renamed with a format suffix to make
+room for the new `*_storage` variants. Update any MCP client configurations
+that reference the old names:
+
+| Old name | New name |
+|---|---|
+| `get_page` | `get_page_md` |
+| `edit_page` | `edit_page_md` |
+| `create_page` | `create_page_md` |
+| `add_content_to_page` | `add_content_md` |
+
+The old names are fully removed; no aliases are provided.
+
+## [0.1.0] - 2026-02-26
+
+### Added
+
+#### Core Actions
+- `read` - Read a specific Confluence page rendered in terminal with Rich
+- `read-recent` - Browse recently viewed pages interactively
+- `edit` - Edit a page in your preferred editor and push changes back
+- `edit-recent` - Select from recently edited pages and edit
+- `download` - Download a page as markdown file
+- `add` - Append or prepend content (markdown or HTML) to a page
+- `create` - Create a new page from content
+- `create-edit` - Create a new page via editor
+- `create-task` - Create a task page with Page Properties macro
+- `search` - Search pages by text query or CQL
+- `list-children` - List child pages (optionally recursive)
+- `test-auth` - Verify authentication credentials
+
+#### Navigation
+- Interactive page selection via fzf (fuzzy finder) with fallback to InquirerPy
+- `--no-fzf` flag to force InquirerPy selector
+
+#### Table Support
+- Complex tables with colspan/rowspan preserved as HTML during round-trips
+- Meeting tables preserved as-is
+- `--table-format yaml` option for easier editing of complex tables
+
+#### Configuration
+- Config file at `~/.config/confluence-markdown/config.json`
+- Multiple named profiles (`--profile`)
+- Per-space editor and table-format settings
+- `--init-config` to generate an example config
+- `--save-config` to persist credentials
+- `--list-profiles` / `--delete-profile` management commands
+
+#### Performance
+- Response caching with configurable TTL (default: 1 hour)
+- Parallel async API calls for batch operations (recursive download, list-children)
+- Automatic retry with exponential backoff on rate limit errors
+
+#### Quality of Life
+- `--raw` flag for plain markdown output (scripting-friendly)
+- `--quiet` / `--verbose` logging modes
+- `--recursive` for recursive child page operations
+- `--output-dir` for batch downloads
+- Shell tab completion via argcomplete (bash/zsh)
+- `--version` flag
+- `--clear-cache` / `--no-cache` cache management
+
+[0.1.0]: https://github.com/jvanvinkenroye/confluence_markdown/releases/tag/v0.1.0

confluence_markdown-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

confluence_markdown-0.1.0/MARKETPLACE.md

@@ -0,0 +1,193 @@
+# Claude Code Marketplace Distribution
+
+This document describes how to distribute `confluence-markdown-mcp` via the Claude Code Marketplace.
+
+## Prerequisites
+
+1. **GitHub Repository** (already set up at https://github.com/jvanvinkenroye/confluence_markdown)
+2. **PyPI Account** with API token for publishing Python packages
+3. **GitHub Secrets** configured:
+   - `PYPI_TOKEN`: Your PyPI API token (with scope "Entire account")
+
+## Setup GitHub Secrets
+
+1. Go to: https://github.com/jvanvinkenroye/confluence_markdown/settings/secrets/actions
+2. Add new secret:
+   - **Name:** `PYPI_TOKEN`
+   - **Value:** Your PyPI API token (from https://pypi.org/account/token/)
+
+## Creating a Release
+
+### 1. Update Version
+
+Edit `pyproject.toml`:
+
+```toml
+[project]
+version = "0.2.0"  # Bump version
+```
+
+### 2. Create Release Notes
+
+Create/update `RELEASE_NOTES.md`:
+
+```markdown
+# v0.2.0 — Enhanced MCP Server
+
+## Features
+
+- ✨ New `*_storage` tools for lossless XHTML access
+- ✨ Human-in-the-loop write confirmation (elicitation support)
+- 🐛 Fixed colspan/rowspan preservation in tables
+- 📚 Comprehensive documentation for Claude Code & Desktop
+
+## Installation
+
+### Claude Code / Desktop
+
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/confluence_markdown",
+        "run",
+        "confluence-markdown-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Command Line
+
+```bash
+uvx --from "git+https://github.com/jvanvinkenroye/confluence_markdown.git@v0.2.0[mcp]" confluence-markdown-mcp
+```
+
+## Tools
+
+13 MCP tools available:
+- Navigation: `list_spaces`, `list_recent_pages`, `search_pages`, `list_children`
+- Read: `get_page_storage`, `get_page_md`
+- Write: `create_page_*`, `edit_page_*`, `add_content_*`
+- Diagnostic: `check_elicitation_support`
+
+## Resources
+
+- `confluence://page/{page_id}` — Markdown view
+- `confluence://page/{page_id}/storage` — XHTML view (lossless)
+
+## Known Issues
+
+- Elicitation (write confirmation) not yet supported by all clients
+- Some Confluence macros may cause 500 errors on older server versions
+
+## Contributors
+
+- Jan Vanvinkenroye (@jvanvinkenroye)
+```
+
+### 3. Commit and Tag
+
+```bash
+git add pyproject.toml RELEASE_NOTES.md
+git commit -m "chore: prepare v0.2.0 release"
+git tag -a v0.2.0 -m "Version 0.2.0: Enhanced MCP Server"
+git push origin main --tags
+```
+
+The GitHub Actions workflow will automatically:
+1. Build the Python package
+2. Create a GitHub Release with artifacts
+3. Publish to PyPI
+
+## Registering in Claude Code Marketplace
+
+### Step 1: Marketplace Registration (via Anthropic)
+
+The Claude Code Marketplace is currently managed by Anthropic. To register:
+
+1. Create an issue in the [Claude Code Marketplace Registry](https://github.com/anthropics/claude-code-marketplace)
+2. Include:
+   - **Title:** `[New Tool] confluence-markdown-mcp`
+   - **Description:**
+     ```
+     MCP server for read/write access to Confluence Data Center pages
+     
+     - GitHub: https://github.com/jvanvinkenroye/confluence_markdown
+     - PyPI: https://pypi.org/project/confluence-markdown/
+     - Features: Storage format (lossless), Markdown, 13 tools
+     ```
+   - **Manifest:** Link to `mcp.json` in your repo
+   - **Installation:** Command for users to install
+
+### Step 2: Prepare Documentation
+
+Ensure your README includes:
+- ✅ Clear installation instructions
+- ✅ MCP server setup for Claude Code and Claude Desktop
+- ✅ All available tools documented
+- ✅ Usage examples
+- ✅ Authentication setup
+- ✅ Troubleshooting
+
+All covered in `/README.md`.
+
+### Step 3: Marketplace Listing
+
+Once approved, the tool will appear in Claude Code's marketplace with:
+- **Name:** confluence-markdown-mcp
+- **Description:** Read and write Confluence pages from Claude
+- **Installation:** One-click install (configured from `mcp.json`)
+- **Authentication:** Guided setup for Confluence credentials
+
+## Distribution Channels
+
+### Users Can Install Via:
+
+1. **PyPI / uvx** (manual command):
+   ```bash
+   uvx --from "git+https://github.com/jvanvinkenroye/confluence_markdown.git[mcp]" confluence-markdown-mcp
+   ```
+
+2. **Claude Code Marketplace** (one-click, if approved):
+   - Search "confluence-markdown"
+   - Click "Install"
+   - Follow credential setup
+
+3. **Direct GitHub** (development):
+   ```bash
+   git clone https://github.com/jvanvinkenroye/confluence_markdown.git
+   cd confluence_markdown
+   uv pip install -e ".[mcp]"
+   ```
+
+4. **Homebrew** (optional, future):
+   ```bash
+   brew install confluence-markdown-mcp
+   ```
+
+## Update Process
+
+1. Make changes in a branch
+2. Update version in `pyproject.toml`
+3. Update `RELEASE_NOTES.md`
+4. Commit and push
+5. Create git tag (`v0.2.0`)
+6. Push tag: `git push origin v0.2.0`
+7. GitHub Actions builds, tests, and publishes automatically
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+- `MAJOR.MINOR.PATCH`
+- Example: `0.2.1` → `0.2.2` (patch fix), `0.3.0` (new features), `1.0.0` (stable release)
+
+## Support
+
+- **Issues:** GitHub Issues (https://github.com/jvanvinkenroye/confluence_markdown/issues)
+- **Discussions:** GitHub Discussions (enable in repo settings)
+- **Documentation:** README.md and inline docstrings