better-confluence-mcp: Instructions file for Claude Code

Project Guidelines

IMPORTANT: Git & Publishing Rules

NEVER execute these commands without explicit user permission:

• git commit
• git tag
• git push
• uv build
• uv publish

Always show the user what you're about to do and wait for their explicit "go ahead" before executing.

Development Workflow

After modifying MCP server code: You must wait for the user to restart Claude Code before calling the updated MCP tools. The MCP server runs as a subprocess and code changes are not reflected until restart.

Project Overview

This is Better Confluence MCP - an MCP server for Confluence with local filesystem caching. It's designed specifically for coding agents like Claude Code, Cursor, and similar AI assistants.

Key Concept

Coding agents work best with files. This MCP syncs Confluence spaces to local .html files, allowing agents to:

1. Sync spaces to local filesystem
2. Edit HTML files using native file tools
3. Push changes back to Confluence

Available Tools

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

Authentication

The server supports two authentication methods:

• Basic Auth (Cloud): CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN
• PAT (Server/Data Center): CONFLUENCE_PERSONAL_TOKEN

Transport

The server only supports stdio transport.

Testing MCP Servers

Using JSON-RPC from Command Line

MCP servers communicate via JSON-RPC over stdio. You can test directly:

# Start the server and send requests via stdin
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

# Or use a heredoc for multiple requests
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