better-confluence-mcp: Instructions file for Codex

AGENTS

Audience: LLM-driven engineering agents

This file provides guidance for autonomous coding agents working inside the Better Confluence MCP repository.

---

What This MCP Does

This MCP is designed for coding agents. It syncs Confluence spaces to local HTML files, so agents can:

1. Sync spaces to .better-confluence-mcp/ directory
2. Edit HTML files using native file tools
3. Push changes back to Confluence

No complex API calls mid-conversation. Just simple file operations.

---

Repository map

Path	Purpose
src/mcp_atlassian/	Library source code (Python ≥ 3.10)
├─ confluence/	Confluence client, mixins, and operations
├─ models/	Pydantic data models for API responses
├─ servers/	FastMCP server implementations
├─ local_storage.py	Local filesystem caching logic
└─ utils/	Shared utilities (auth, logging, SSL)
tests/	Pytest test suite with fixtures

---

Available MCP Tools

Tool	Description
confluence_sync_space	Sync a space to local filesystem (incremental by default)
confluence_read_page	Fetch a single page and save locally
confluence_push_page_update	Push local HTML changes back to Confluence

---

Mandatory dev workflow

uv sync --frozen --all-extras --dev  # install dependencies
pre-commit install                    # setup hooks
pre-commit run --all-files           # Ruff + Prettier + Pyright
uv run pytest                        # run full test suite

Tests must pass and lint/typing must be clean before committing.

---

Testing the MCP Server

Using MCP Inspector (Recommended)

npx @modelcontextprotocol/inspector uv --directory . run better-confluence-mcp

Using JSON-RPC from Command Line

MCP servers communicate via JSON-RPC over stdio. Test directly:

# Initialize the server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | uv run better-confluence-mcp

# Multiple requests with heredoc
uv run better-confluence-mcp << 'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF