Confluence MCP Server

# Project Overview

This project is a **Confluence MCP (Model Context Protocol) System**. It consists of a Python server that fetches data from a Confluence Wiki via its REST API and exposes it as a set of tools that can be consumed by a Large Language Model (LLM).

The system uses the **Model Context Protocol (MCP)** with stdio communication, allowing seamless integration with LLM applications. Content is automatically converted from Confluence's HTML format to clean Markdown for better LLM context efficiency.

## Architecture

- **MCP Server** (server.py): Implements three tools using the MCP protocol
  - Supports **two transport modes**: stdio (local) and HTTP/SSE (Docker)
  - `search_confluence`: Search for pages, blog posts, or attachments
  - `read_page`: Fetch full page content (converted to Markdown)
  - `list_space_content`: List all pages in a Confluence space

- **MCP Client** (host.py): Simple CLI client for testing the server
  - Default: stdio connection for local testing
  - With `--http`: HTTP/SSE connection for Docker containers

- **Docker Support**: Containerization with HTTP/SSE transport for production deployment

## Building and Running

### Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended package manager)
- Docker (optional, for containerized deployment)

### 1. Configure Environment Variables

This project uses a `.env` file to manage sensitive data like API keys.

1.  **Create a `.env` file:**
    Copy the example file:
    ```bash
    cp .env.example .env
    ```

2.  **Edit the `.env` file:**
    Open the `.env` file and add your Confluence credentials:
    - `CONFLUENCE_URL`: Your Confluence instance URL
    - `CONFLUENCE_USERNAME`: Your Confluence email
    - `CONFLUENCE_API_TOKEN`: Your Confluence API token

### 2. Install Dependencies

#### Using uv (recommended)

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies and create .venv
uv sync
```

#### Using pip

```bash
pip install -r requirements.txt
```

### 3. Run Locally

You can run the server and client directly without Docker:

```bash
# With uv (no activation needed)
uv run python host.py search_confluence '{"query": "My search query"}'
uv run python host.py read_page '{"page_id": "123456"}'
uv run python host.py list_space_content '{"space_key": "TEAM"}'

# Or activate venv first
source .venv/bin/activate
python host.py search_confluence '{"query": "My search query"}'
```

### 3b. Test with MCP Inspector (Recommended)

The MCP Inspector provides a visual interface for testing:

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Create config from example
cp mcp-config.example.json mcp-config.json
# Edit mcp-config.json with your credentials

# Launch inspector
mcp-inspector mcp-config.json
```

Open `http://localhost:5173` in your browser to test the tools interactively.

### 4. Run with Docker (HTTP/SSE Transport)

Build the Docker image:

```bash
docker build -t confluence-mcp .
```

Run the container with HTTP/SSE communication:

```bash
docker run --rm -p 8000:8000 --env-file .env confluence-mcp
```

Connect to the containerized server:

```bash
# Use --http flag to connect via HTTP
python host.py --http http://localhost:8000 search_confluence '{"query": "test"}'
```

**Note**: The Docker container runs with HTTP/SSE transport on port 8000, allowing remote access and network communication.

## Development Conventions

### Code Style

This project follows standard Python coding conventions (PEP 8).

### Project Structure

- `server.py`: The core MCP server application using FastMCP with stdio transport
- `host.py`: An MCP client for testing and interacting with the server
- `pyproject.toml`: Project metadata and dependencies (uv configuration)
- `Dockerfile`: Container definition supporting stdio-based MCP communication
- `requirements.txt`: Python dependencies including MCP SDK, FastMCP, and html2text
- `mcp-config.example.json`: Example configuration for MCP Inspector
- `func_req.md`: The functional requirements specification
- `.env.example`: Template for environment variables
- `TESTING.md`: Comprehensive testing guide with troubleshooting
- `GEMINI.md`: This file, providing an overview of the project

## Key Features

- **MCP Protocol Compliance**: Uses the official Model Context Protocol over stdio
- **Markdown Conversion**: Automatically converts Confluence HTML to Markdown for better LLM context
- **Error Handling**: Graceful handling of 401 (Unauthorized) and 404 (Not Found) errors
- **Three Core Tools**:
  - Search across Confluence content
  - Read full page content with Markdown formatting
  - List all pages in a workspace