# Confluence MCP Server

Model Context Protocol (MCP) server for integrating Confluence with AI agents. This server allows AI assistants to search, read, and retrieve documentation from your Confluence workspace.

## Features

- 🔍 **Search Confluence** - Full-text and CQL search across spaces
- 📄 **Get Page by ID** - Retrieve complete page content by ID
- 📝 **Get Page by Title** - Find pages by exact title match
- 📚 **List Space Pages** - Get all pages in a space
- 🌲 **Get Page Children** - Navigate page hierarchies
- 📥 **Sync Docs** - Sync Confluence pages to local markdown files
- 📤 **Push MD to Confluence** - Push markdown files to Confluence (create/update pages)

## Installation

```bash
git clone https://github.com/harshpuri84/confluence-mcp.git
cd confluence-mcp
npm install
npm run build
```

## Configuration

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

2. Configure your Confluence credentials:
```env
CONFLUENCE_BASE_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-api-token
CONFLUENCE_SPACE_KEY=DOCS
CONFLUENCE_PAGE_LIMIT=10
CONFLUENCE_SYNC_DIR=./confluence-docs
```

### Getting Confluence API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a descriptive name (e.g., "MCP Server")
4. Copy the token and add it to your `.env` file

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": [
        "/Users/harsh.puri/Documents/AI-airlcl/mcp-servers/confluence-mcp/dist/index.js"
      ],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_SPACE_KEY": "DOCS"
      }
    }
  }
}
```

Restart Claude Desktop after configuration.

## Available Tools

### search_confluence
Search Confluence for pages matching a query.

**Parameters:**
- `query` (required): Search query or CQL statement
- `limit` (optional): Maximum results (default: 10)
- `spaceKey` (optional): Restrict to specific space

**Example queries:**
```
"freight operations"
"text ~ \"booking\" AND space = DOCS"
"title ~ \"API\" AND type = page"
```

### get_page_by_id
Get a Confluence page by its ID.

**Parameters:**
- `pageId` (required): The page ID
- `expandBody` (optional): Include content (default: true)

### get_page_by_title
Find a page by exact title match.

**Parameters:**
- `title` (required): Exact page title
- `spaceKey` (required): Space key

### get_space_pages
List all pages in a space.

**Parameters:**
- `spaceKey` (required): The space key
- `limit` (optional): Max pages (default: 25)

### get_page_children
Get child pages of a parent page.

**Parameters:**
- `pageId` (required): Parent page ID
- `limit` (optional): Max children (default: 25)

### sync_confluence_docs
Sync Confluence pages to local markdown files. Supports syncing entire spaces, search results, or specific pages.

**Parameters:**
- `spaceKey` (optional): Space key to sync all pages from
- `query` (optional): CQL query to sync matching pages
- `pageIds` (optional): Array of specific page IDs to sync
- `outputDir` (optional): Output directory (default: ./confluence-docs)
- `includeChildren` (optional): Include child pages (default: false)
- `recursive` (optional): Recursively sync child pages (default: false)

**Note:** You must provide at least one of `spaceKey`, `query`, or `pageIds`.

## Syncing Docs to Local Files

### Using the Standalone Sync Script

The Confluence MCP includes a standalone CLI script for syncing documentation:

```bash
# Build the project first
npm run build

# Sync all pages from a space
node dist/sync.js space DOCS

# Sync to a custom directory
node dist/sync.js space DOCS ./my-docs

# Sync recursively (includes all child pages)
node dist/sync.js space DOCS --recursive

# Sync pages matching a query
node dist/sync.js query "API documentation"

# Sync with space filter
node dist/sync.js query "best practices" --space DOCS

# Sync specific pages by ID
node dist/sync.js pages 123456 789012 345678
```

### Using the MCP Tool

You can also sync docs via the MCP `sync_confluence_docs` tool:

```json
{
  "tool": "sync_confluence_docs",
  "arguments": {
    "spaceKey": "DOCS",
    "outputDir": "./confluence-docs",
    "recursive": true
  }
}
```

### Output Format

Synced files are saved as Markdown with frontmatter:
- Files are organized by space key: `{outputDir}/{spaceKey}/{page-title}.md`
- Each file includes metadata (ID, title, space, URL, version, last modified)
- HTML content is converted to Markdown
- Child pages are included if `recursive` or `includeChildren` is true

Example output structure:
```
confluence-docs/
  DOCS/
    Getting-Started.md
    API-Reference.md
    Best-Practices.md
    Sub-Page.md
```

## Pushing Markdown Files to Confluence

### Using the Standalone Push Script

Push markdown files to Confluence using the CLI script:

```bash
# Build the project first
npm run build

# Push a single markdown file
node dist/push.js file document.md --space DOCS

# Push with parent page (create as child page)
node dist/push.js file document.md --space DOCS --parent 123456

# Push all markdown files from a directory
node dist/push.js dir ./docs --space DOCS

# Push directory with parent page
node dist/push.js dir ./docs --space DOCS --parent 123456

# Create new pages only (don't update existing)
node dist/push.js file document.md --space DOCS --no-update

# Or use npm script
npm run push file document.md --space DOCS
```

### Using the MCP Tool

You can also push markdown files via the MCP `push_md_to_confluence` tool:

```json
{
  "tool": "push_md_to_confluence",
  "arguments": {
    "filePath": "./document.md",
    "spaceKey": "DOCS",
    "updateExisting": true
  }
}
```

Or push an entire directory:

```json
{
  "tool": "push_md_to_confluence",
  "arguments": {
    "directory": "./docs",
    "spaceKey": "DOCS",
    "parentPageId": "123456"
  }
}
```

### File Format

Markdown files can include frontmatter for metadata:

```markdown
---
id: 123456
title: My Document Title
spaceKey: DOCS
---

# My Document

Content goes here...
```

**Frontmatter fields:**
- `id` (optional): Existing Confluence page ID - if provided, will update that page
- `title` (optional): Page title - defaults to filename if not provided
- `spaceKey` (optional): Space key - can be provided via CLI/API parameter instead

**Behavior:**
- If `id` is in frontmatter and page exists → Updates the page
- If `title` matches existing page in space → Updates the page (if `updateExisting` is true)
- Otherwise → Creates a new page
- Markdown is converted to HTML automatically
- Supports standard markdown: headings, lists, code blocks, links, etc.

### Example AI Prompts

Once configured, you can ask Claude:

- "Search our Confluence for documentation about booking workflows"
- "Get the AI Agentic Playbook page from Confluence"
- "Show me all pages in the DOCS space"
- "Find pages about rate determination in Confluence"
- "Get the child pages of page ID 123456"
- "Sync all pages from the DOCS space to local files"
- "Sync all API documentation pages matching 'API' query"
- "Push markdown file document.md to Confluence"
- "Push all markdown files from ./docs directory to Confluence"

## Integration with AI Agents

This MCP server enables your AI agents (from the playbook) to:

1. **Retrieve SOPs** - Agents can fetch standard operating procedures
   ```typescript
   // Rate Agent example
   const sopContent = await mcp.call('search_confluence', {
     query: 'text ~ "rate calculation SOP"'
   });
   ```

2. **Access Knowledge Base** - Build RAG pipeline with Confluence as source
   ```typescript
   // Learning Agent example
   const bestPractices = await mcp.call('get_page_by_title', {
     title: 'Best Practices - Booking Validation',
     spaceKey: 'DOCS'
   });
   ```

3. **Context-Aware Assistance** - Provide agents with real-time documentation
   ```typescript
   // Exception Handler example
   const dgProcedure = await mcp.call('search_confluence', {
     query: 'DG Class 3 handling procedure',
     spaceKey: 'COMPLIANCE'
   });
   ```

## Use Cases (logistics agent examples)

### 1. SOP Retrieval
```
User: "What's the DG process for Class 3 cargo?"
  ↓
Agent searches Confluence: search_confluence("DG Class 3 procedure")
  ↓
Returns: Complete SOP with approval workflow
  ↓
Agent answers with citations
```

### 2. Master Data Validation
```
Booking Validator needs to check customer policies
  ↓
Searches: get_page_by_title("Customer X - Shipping Policy", "CUSTOMERS")
  ↓
Validates booking against documented policies
```

### 3. Learning Agent Improvement
```
Learning Agent detects pattern: "50% shipper mismatches"
  ↓
Searches Confluence: search_confluence("shipper master data rules")
  ↓
Finds updated SOP: "Always use legal name, not trade name"
  ↓
Updates agent prompt with Confluence documentation
```

### 4. Exception Handler Context
```
Exception: "Customs clearance delayed"
  ↓
Agent searches: search_confluence("customs clearance troubleshooting")
  ↓
Retrieves relevant procedures
  ↓
Suggests actions to operator with documentation links
```

## Troubleshooting

### Authentication Errors
- Verify your API token is correct
- Check that your email matches your Atlassian account
- Ensure the token has sufficient permissions

### Page Not Found
- Verify the space key is correct
- Check page permissions (must be readable by your account)
- Try searching by ID instead of title

### Connection Errors
- Verify CONFLUENCE_BASE_URL format (include https://)
- Check network/firewall settings
- Ensure your Confluence instance is accessible

## Development

```bash
# Watch mode for development
npm run dev

# Build
npm run build

# Run locally
npm start
```

## Security Notes

⚠️ **Important Security Considerations:**

1. **API Token Storage**: Never commit `.env` file to git
2. **Least Privilege**: Create API token with minimum required permissions
3. **Token Rotation**: Rotate tokens regularly (every 90 days)
4. **Access Logging**: Monitor token usage in Atlassian audit logs
5. **Scope Restriction**: Limit access to specific spaces if possible

## Roadmap

Future enhancements:
- [x] Sync Confluence docs to local markdown files
- [x] Push markdown files to Confluence (create/update pages)
- [ ] Add comments to pages
- [ ] Attachment download
- [ ] Page versioning and history
- [ ] Advanced CQL query builder
- [ ] Caching layer for frequently accessed pages
- [ ] Webhook integration for real-time updates
- [ ] Incremental sync (only sync changed pages)
- [ ] Sync with git integration

## License

MIT

## Related Documentation

- [Model Context Protocol Spec](https://spec.modelcontextprotocol.io/)
- [Confluence REST API Docs](https://developer.atlassian.com/cloud/confluence/rest/v2/)