🌐 Confluence MCP Server

A powerful Model Context Protocol (MCP) server that brings Atlassian Confluence integration directly to any editor or application that supports MCP

✨ Features

🚀 New in v0.3.0 - Optimized Architecture

9 Strategic MCP Tools - Optimized from 8 tools with enhanced workflow capabilities
Domain-Based Architecture - Clean separation into 3 domains: Spaces, Pages, and Search
Enhanced Navigation - New tools for space lookup, page hierarchy, and content discovery
Improved Performance - 1871 tests passing with optimized build process

📚 Access Confluence Directly From Your Editor

Browse your Confluence spaces without leaving your IDE
Get detailed page information with formatted content
Navigate page hierarchies with child page discovery
Create, update, and manage Confluence content directly

🔍 Powerful Search Capabilities

Search pages using text queries or advanced CQL (Confluence Query Language)
Support for space filtering, content type filtering, and result ordering
Rich markdown formatting with page previews and direct links
Renamed confluence_search_pages to confluence_search for simplicity

📝 Smart Content Processing

Automatic conversion of Confluence's storage format to readable markdown
Support for formatted text, tables, macros, and attachments
Full CRUD operations for page management
Strategic workflow tools for better user experience

🚀 Quick Start

Installation

The easiest way to use this MCP server is to install it directly via npm/bunx. No local setup required!

For Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Cursor IDE

Add this configuration to your Cursor IDE MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Any MCP Client

Use this configuration pattern for any MCP-compatible client:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

🔑 Getting Your Confluence API Token

Go to Atlassian API Tokens

Click "Create API token"

Give it a name (e.g., "MCP Confluence")

Copy the token and use it in your configuration

Important: Use the token exactly as provided (no quotes needed in the env section)

Alternative: Using npx instead of bunx

If you prefer npx over bunx, you can also use:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "npx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Testing Your Setup

After adding the configuration:

Restart your MCP client (Claude Desktop, Cursor, etc.)
Try this command to test the connection:
```
Show me my Confluence spaces.
```

That's it! You're ready to use Confluence directly from your MCP client.

🛠️ Development Setup

Click here if you want to develop or customize this MCP server

Development Installation

For development or customization:

# Clone the repository
git clone https://github.com/Dsazz/mcp-confluence.git
cd mcp-confluence

# Install dependencies
bun install

# Build the project
bun run build

# Set up environment variables
cp .env.example .env
# Edit .env with your Confluence credentials

Configuration

Create a .env file with the following variables:

CONFLUENCE_HOST_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token
NODE_ENV=development

Development Tools

Code Quality Tools

The project uses Biome for code formatting and linting, replacing the previous ESLint setup. Biome provides:

Fast, unified formatting and linting
TypeScript-first tooling
Zero configuration needed
Consistent code style enforcement

To format and lint your code:

# Format code
bun format

# Check code for issues
bun check

# Type check
bun typecheck

MCP Inspector

The MCP Inspector is a powerful tool for testing and debugging your MCP server.

# Run the inspector (no separate build step needed)
bun run inspect

The inspector automatically:

Loads environment variables from .env
Cleans up occupied ports (5175, 3002)
Builds the project when needed
Starts the MCP server with your configuration
Launches the inspector UI

Visit the inspector at http://localhost:5175?proxyPort=3002

The inspector UI allows you to:

View all available MCP capabilities
Execute tools and examine responses
Analyze the JSON communication
Test with different parameters

For more details, see the MCP Inspector GitHub repository.

🧰 Available Tools

🌟 Strategic Workflow Tools

Tool	Description	Parameters	Returns
`confluence_get_spaces`	List accessible Confluence spaces with optional filtering	See space parameters below	Markdown-formatted list of spaces
`confluence_get_space_by_key`	Get specific space information by space key	`spaceKey`, optional expand flags	Markdown-formatted space details
`confluence_get_pages_by_space`	Get all pages within a specific space	`spaceId`, optional pagination	Markdown-formatted page list
`confluence_get_page`	Get detailed information about a specific page with content	`pageId`, optional content flags	Markdown-formatted page details
`confluence_get_child_pages`	Get child pages of a specific page for hierarchy navigation	`pageId`, optional pagination	Markdown-formatted child pages
`confluence_search`	Search pages using text queries or CQL (renamed from search_pages)	See search parameters below	Markdown-formatted search results
`confluence_create_page`	Create a new page in Confluence	See page creation parameters	Markdown-formatted page details
`confluence_update_page`	Update an existing page in Confluence	See page update parameters	Markdown-formatted page details
`confluence_delete_page`	Delete a page from Confluence	`pageId`	Confirmation message

Space Parameters

The confluence_get_spaces tool supports these parameters:

Basic Options:

type: String ("global" or "personal", optional) - Filter by space type
limit: Number (1-100, default: 25) - Maximum number of spaces to return
start: Number (default: 0) - Pagination offset for large result sets

Examples:

# Basic usage - get all accessible spaces
confluence_get_spaces

# Get only global spaces
confluence_get_spaces type:"global" limit:10

# Pagination example
confluence_get_spaces start:25 limit:25

Page Parameters

The confluence_get_page tool supports these parameters:

Required:

pageId: String - The ID of the page to retrieve

Content Options:

includeContent: Boolean (default: true) - Include full page content
includeComments: Boolean (default: false) - Include comment count
expand: String (optional) - Additional fields to expand (comma-separated)

Examples:

# Basic usage with content
confluence_get_page 12345

# Get page without content
confluence_get_page 12345 includeContent:false

# Get page with comments and extra data
confluence_get_page 12345 includeComments:true expand:"version,space"

Search Parameters

The confluence_search tool supports both simple and advanced search:

Basic Search:

query: String - Text search query (searches titles and content)
spaceKey: String (optional) - Limit search to specific space
type: String ("page" or "blogpost", optional) - Content type filter

Advanced Search (CQL):

query: String - Full CQL query for advanced searches
Examples: text~"specific phrase", type=page AND space.key="DEV"

Result Options:

limit: Number (1-100, default: 25) - Maximum number of results
start: Number (default: 0) - Pagination offset
orderBy: String ("relevance", "created", "modified", "title") - Sort order

Examples:

# Simple text search
confluence_search query:"project documentation"

# Search in specific space
confluence_search query:"API guide" spaceKey:"DEV"

# Advanced CQL search
confluence_search query:'text~"user guide" AND type=page'

# Search with custom ordering
confluence_search query:"meeting notes" orderBy:"modified" limit:10

Page Management Parameters

Page Creation (confluence_create_page):

spaceId: String - The ID of the space where the page will be created
title: String - The title of the new page
content: String - The content of the page (supports Confluence storage format)
parentPageId: String (optional) - The ID of the parent page
status: String ("current" or "draft", default: "current") - Page status

Page Update (confluence_update_page):

pageId: String - The ID of the page to update
title: String (optional) - New title for the page
content: String (optional) - New content for the page
versionNumber: Number - Current version number of the page
versionMessage: String (optional) - Message describing the changes

Examples:

# Create a new page
confluence_create_page spaceId:"123456" title:"New Documentation" content:"<p>Initial content</p>"

# Update an existing page
confluence_update_page pageId:"789012" title:"Updated Title" content:"<p>Updated content</p>" versionNumber:2

# Get child pages for navigation
confluence_get_child_pages pageId:"123456" limit:10

📁 Project Structure (v0.3.0 - Optimized Architecture)

 src/
  ├── core/                    # Core functionality and configurations
  │   ├── errors/              # Error handling utilities
  │   ├── logging/             # Logging infrastructure
  │   ├── responses/           # Response formatting
  │   ├── server/              # MCP server setup
  │   ├── tools/               # Base tool patterns
  │   └── utils/               # General utilities
  ├── features/                # Feature implementations
  │   └── confluence/          # Confluence integration
  │       ├── client/          # HTTP client infrastructure
  │       │   ├── config/      # Client configuration
  │       │   ├── errors/      # Client-specific errors
  │       │   ├── http/        # HTTP client implementations
  │       │   │   ├── utils/   # HTTP utilities
  │       │   │   ├── v1/      # V1 API client (search)
  │       │   │   └── v2/      # V2 API client (CRUD)
  │       │   └── responses/   # Response models
  │       ├── domains/         # Domain-based architecture (NEW)
  │       │   ├── spaces/      # Space management domain
  │       │   │   ├── handlers/     # Space operation handlers
  │       │   │   ├── models/       # Space data models
  │       │   │   ├── use-cases/    # Space business logic
  │       │   │   ├── validators/   # Space validation
  │       │   │   └── formatters/   # Space response formatting
  │       │   ├── pages/       # Page management domain
  │       │   │   ├── handlers/     # Page operation handlers
  │       │   │   ├── models/       # Page data models
  │       │   │   ├── use-cases/    # Page business logic
  │       │   │   ├── validators/   # Page validation
  │       │   │   └── formatters/   # Page response formatting
  │       │   └── search/      # Search domain
  │       │       ├── handlers/     # Search operation handlers
  │       │       ├── models/       # Search data models
  │       │       ├── use-cases/    # Search business logic
  │       │       ├── validators/   # Search validation
  │       │       └── formatters/   # Search response formatting
  │       ├── shared/          # Shared utilities across domains
  │       │   ├── formatters/  # Common formatters
  │       │   └── validators/  # Common validators
  │       └── tools/           # MCP tool orchestration
  │           ├── handlers.ts  # Unified tool handlers
  │           ├── mcp.ts       # MCP tool definitions
  │           └── routing.ts   # Tool routing logic
  └── test/                    # Test suite (1871 tests)
      ├── integration/         # Integration tests
      ├── unit/               # Unit tests (domain-organized)
      │   ├── core/           # Core functionality tests
      │   └── features/       # Feature tests (by domain)
      │       └── confluence/
      │           └── domains/ # Domain-specific tests
      │               ├── spaces/   # Space domain tests
      │               ├── pages/    # Page domain tests
      │               └── search/   # Search domain tests
      └── utils/              # Test utilities

Architecture Overview

The Confluence MCP Server uses a dual-client architecture for optimal API version management:

V1 Client (http-client-v1.impl.ts): Handles search operations and CQL queries
V2 Client (http-client-v2.impl.ts): Manages CRUD operations for spaces and pages
Operation Router (operation.router.ts): Intelligently routes requests to the appropriate API version
Factory Pattern (http-client.factory.ts): Provides clean dependency injection for clients

This architecture ensures:

Optimal Performance: Each operation uses the most suitable API version
Future Compatibility: Easy to add new API versions or deprecate old ones
Clean Separation: Clear boundaries between different API capabilities
Type Safety: Full TypeScript support across all client implementations

NPM Scripts

Command	Description
`bun dev`	Run the server in development mode with hot reload
`bun build`	Build the project for production
`bun start`	Start the production server
`bun format`	Format code using Biome
`bun lint`	Lint code using Biome
`bun check`	Run Biome checks on code
`bun typecheck`	Run TypeScript type checking
`bun test`	Run tests
`bun inspect`	Start the MCP Inspector for debugging

🔧 Troubleshooting

NPM Installation Issues

Package Not Found

If you get a "package not found" error:

# Make sure you're using the correct scoped package name
bunx @dsazz/mcp-confluence@latest

# Or try with explicit npm registry
npm install -g @dsazz/mcp-confluence --registry https://registry.npmjs.org

Environment Variables Not Found

If the server fails to start with environment variable errors:

For bunx usage: Create a .env file in your working directory:

# Create .env file in your current directory
echo "CONFLUENCE_HOST_URL=https://your-domain.atlassian.net" > .env
echo "CONFLUENCE_USER_EMAIL=your-email@example.com" >> .env
echo "CONFLUENCE_API_TOKEN=your-api-token" >> .env

For MCP configuration: Set environment variables in your MCP config:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

API Connection Issues

Invalid Credentials

Verify your Confluence API token is correct
Ensure your email matches your Atlassian account
Check that your Confluence URL is correct (include https://)

Network/Firewall Issues

Ensure your network allows connections to your Confluence instance
Check if your organization requires VPN access
Verify firewall settings allow outbound HTTPS connections

Development Issues

Build Failures

# Clear dependencies and reinstall
rm -rf node_modules bun.lockb
bun install

# Clean build
rm -rf dist
bun run build

TypeScript Errors

# Run type checking
bun run typecheck

# Check for linting issues
bun run check

📝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Development workflow
Branching strategy
Commit message format
Pull request process
Code style guidelines

📘 Resources

📄 License

MIT © Stanislav Stepanenko

_{Built with ❤️ for a better developer experience}

🌐 Confluence MCP Server

A powerful Model Context Protocol (MCP) server that brings Atlassian Confluence integration directly to any editor or application that supports MCP

✨ Features

🚀 New in v0.3.0 - Optimized Architecture

9 Strategic MCP Tools - Optimized from 8 tools with enhanced workflow capabilities
Domain-Based Architecture - Clean separation into 3 domains: Spaces, Pages, and Search
Enhanced Navigation - New tools for space lookup, page hierarchy, and content discovery
Improved Performance - 1871 tests passing with optimized build process

📚 Access Confluence Directly From Your Editor

Browse your Confluence spaces without leaving your IDE
Get detailed page information with formatted content
Navigate page hierarchies with child page discovery
Create, update, and manage Confluence content directly

🔍 Powerful Search Capabilities

Search pages using text queries or advanced CQL (Confluence Query Language)
Support for space filtering, content type filtering, and result ordering
Rich markdown formatting with page previews and direct links
Renamed confluence_search_pages to confluence_search for simplicity

📝 Smart Content Processing

Automatic conversion of Confluence's storage format to readable markdown
Support for formatted text, tables, macros, and attachments
Full CRUD operations for page management
Strategic workflow tools for better user experience

🚀 Quick Start

Installation

The easiest way to use this MCP server is to install it directly via npm/bunx. No local setup required!

For Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Cursor IDE

Add this configuration to your Cursor IDE MCP settings:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

For Any MCP Client

Use this configuration pattern for any MCP-compatible client:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

🔑 Getting Your Confluence API Token

Go to Atlassian API Tokens

Click "Create API token"

Give it a name (e.g., "MCP Confluence")

Copy the token and use it in your configuration

Important: Use the token exactly as provided (no quotes needed in the env section)

Alternative: Using npx instead of bunx

If you prefer npx over bunx, you can also use:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "npx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
      }
    }
  }
}

Testing Your Setup

After adding the configuration:

Restart your MCP client (Claude Desktop, Cursor, etc.)
Try this command to test the connection:
```
Show me my Confluence spaces.
```

That's it! You're ready to use Confluence directly from your MCP client.

🛠️ Development Setup

Click here if you want to develop or customize this MCP server

Development Installation

For development or customization:

# Clone the repository
git clone https://github.com/Dsazz/mcp-confluence.git
cd mcp-confluence

# Install dependencies
bun install

# Build the project
bun run build

# Set up environment variables
cp .env.example .env
# Edit .env with your Confluence credentials

Configuration

Create a .env file with the following variables:

CONFLUENCE_HOST_URL=https://your-domain.atlassian.net
CONFLUENCE_USER_EMAIL=your-email@example.com
CONFLUENCE_API_TOKEN=your-confluence-api-token
NODE_ENV=development

Development Tools

Code Quality Tools

The project uses Biome for code formatting and linting, replacing the previous ESLint setup. Biome provides:

Fast, unified formatting and linting
TypeScript-first tooling
Zero configuration needed
Consistent code style enforcement

To format and lint your code:

# Format code
bun format

# Check code for issues
bun check

# Type check
bun typecheck

MCP Inspector

The MCP Inspector is a powerful tool for testing and debugging your MCP server.

# Run the inspector (no separate build step needed)
bun run inspect

The inspector automatically:

Loads environment variables from .env
Cleans up occupied ports (5175, 3002)
Builds the project when needed
Starts the MCP server with your configuration
Launches the inspector UI

Visit the inspector at http://localhost:5175?proxyPort=3002

The inspector UI allows you to:

View all available MCP capabilities
Execute tools and examine responses
Analyze the JSON communication
Test with different parameters

For more details, see the MCP Inspector GitHub repository.

🧰 Available Tools

🌟 Strategic Workflow Tools

Tool	Description	Parameters	Returns
`confluence_get_spaces`	List accessible Confluence spaces with optional filtering	See space parameters below	Markdown-formatted list of spaces
`confluence_get_space_by_key`	Get specific space information by space key	`spaceKey`, optional expand flags	Markdown-formatted space details
`confluence_get_pages_by_space`	Get all pages within a specific space	`spaceId`, optional pagination	Markdown-formatted page list
`confluence_get_page`	Get detailed information about a specific page with content	`pageId`, optional content flags	Markdown-formatted page details
`confluence_get_child_pages`	Get child pages of a specific page for hierarchy navigation	`pageId`, optional pagination	Markdown-formatted child pages
`confluence_search`	Search pages using text queries or CQL (renamed from search_pages)	See search parameters below	Markdown-formatted search results
`confluence_create_page`	Create a new page in Confluence	See page creation parameters	Markdown-formatted page details
`confluence_update_page`	Update an existing page in Confluence	See page update parameters	Markdown-formatted page details
`confluence_delete_page`	Delete a page from Confluence	`pageId`	Confirmation message

Space Parameters

The confluence_get_spaces tool supports these parameters:

Basic Options:

type: String ("global" or "personal", optional) - Filter by space type
limit: Number (1-100, default: 25) - Maximum number of spaces to return
start: Number (default: 0) - Pagination offset for large result sets

Examples:

# Basic usage - get all accessible spaces
confluence_get_spaces

# Get only global spaces
confluence_get_spaces type:"global" limit:10

# Pagination example
confluence_get_spaces start:25 limit:25

Page Parameters

The confluence_get_page tool supports these parameters:

Required:

pageId: String - The ID of the page to retrieve

Content Options:

includeContent: Boolean (default: true) - Include full page content
includeComments: Boolean (default: false) - Include comment count
expand: String (optional) - Additional fields to expand (comma-separated)

Examples:

# Basic usage with content
confluence_get_page 12345

# Get page without content
confluence_get_page 12345 includeContent:false

# Get page with comments and extra data
confluence_get_page 12345 includeComments:true expand:"version,space"

Search Parameters

The confluence_search tool supports both simple and advanced search:

Basic Search:

query: String - Text search query (searches titles and content)
spaceKey: String (optional) - Limit search to specific space
type: String ("page" or "blogpost", optional) - Content type filter

Advanced Search (CQL):

query: String - Full CQL query for advanced searches
Examples: text~"specific phrase", type=page AND space.key="DEV"

Result Options:

limit: Number (1-100, default: 25) - Maximum number of results
start: Number (default: 0) - Pagination offset
orderBy: String ("relevance", "created", "modified", "title") - Sort order

Examples:

# Simple text search
confluence_search query:"project documentation"

# Search in specific space
confluence_search query:"API guide" spaceKey:"DEV"

# Advanced CQL search
confluence_search query:'text~"user guide" AND type=page'

# Search with custom ordering
confluence_search query:"meeting notes" orderBy:"modified" limit:10

Page Management Parameters

Page Creation (confluence_create_page):

spaceId: String - The ID of the space where the page will be created
title: String - The title of the new page
content: String - The content of the page (supports Confluence storage format)
parentPageId: String (optional) - The ID of the parent page
status: String ("current" or "draft", default: "current") - Page status

Page Update (confluence_update_page):

pageId: String - The ID of the page to update
title: String (optional) - New title for the page
content: String (optional) - New content for the page
versionNumber: Number - Current version number of the page
versionMessage: String (optional) - Message describing the changes

Examples:

# Create a new page
confluence_create_page spaceId:"123456" title:"New Documentation" content:"<p>Initial content</p>"

# Update an existing page
confluence_update_page pageId:"789012" title:"Updated Title" content:"<p>Updated content</p>" versionNumber:2

# Get child pages for navigation
confluence_get_child_pages pageId:"123456" limit:10

📁 Project Structure (v0.3.0 - Optimized Architecture)

 src/
  ├── core/                    # Core functionality and configurations
  │   ├── errors/              # Error handling utilities
  │   ├── logging/             # Logging infrastructure
  │   ├── responses/           # Response formatting
  │   ├── server/              # MCP server setup
  │   ├── tools/               # Base tool patterns
  │   └── utils/               # General utilities
  ├── features/                # Feature implementations
  │   └── confluence/          # Confluence integration
  │       ├── client/          # HTTP client infrastructure
  │       │   ├── config/      # Client configuration
  │       │   ├── errors/      # Client-specific errors
  │       │   ├── http/        # HTTP client implementations
  │       │   │   ├── utils/   # HTTP utilities
  │       │   │   ├── v1/      # V1 API client (search)
  │       │   │   └── v2/      # V2 API client (CRUD)
  │       │   └── responses/   # Response models
  │       ├── domains/         # Domain-based architecture (NEW)
  │       │   ├── spaces/      # Space management domain
  │       │   │   ├── handlers/     # Space operation handlers
  │       │   │   ├── models/       # Space data models
  │       │   │   ├── use-cases/    # Space business logic
  │       │   │   ├── validators/   # Space validation
  │       │   │   └── formatters/   # Space response formatting
  │       │   ├── pages/       # Page management domain
  │       │   │   ├── handlers/     # Page operation handlers
  │       │   │   ├── models/       # Page data models
  │       │   │   ├── use-cases/    # Page business logic
  │       │   │   ├── validators/   # Page validation
  │       │   │   └── formatters/   # Page response formatting
  │       │   └── search/      # Search domain
  │       │       ├── handlers/     # Search operation handlers
  │       │       ├── models/       # Search data models
  │       │       ├── use-cases/    # Search business logic
  │       │       ├── validators/   # Search validation
  │       │       └── formatters/   # Search response formatting
  │       ├── shared/          # Shared utilities across domains
  │       │   ├── formatters/  # Common formatters
  │       │   └── validators/  # Common validators
  │       └── tools/           # MCP tool orchestration
  │           ├── handlers.ts  # Unified tool handlers
  │           ├── mcp.ts       # MCP tool definitions
  │           └── routing.ts   # Tool routing logic
  └── test/                    # Test suite (1871 tests)
      ├── integration/         # Integration tests
      ├── unit/               # Unit tests (domain-organized)
      │   ├── core/           # Core functionality tests
      │   └── features/       # Feature tests (by domain)
      │       └── confluence/
      │           └── domains/ # Domain-specific tests
      │               ├── spaces/   # Space domain tests
      │               ├── pages/    # Page domain tests
      │               └── search/   # Search domain tests
      └── utils/              # Test utilities

Architecture Overview

The Confluence MCP Server uses a dual-client architecture for optimal API version management:

V1 Client (http-client-v1.impl.ts): Handles search operations and CQL queries
V2 Client (http-client-v2.impl.ts): Manages CRUD operations for spaces and pages
Operation Router (operation.router.ts): Intelligently routes requests to the appropriate API version
Factory Pattern (http-client.factory.ts): Provides clean dependency injection for clients

This architecture ensures:

Optimal Performance: Each operation uses the most suitable API version
Future Compatibility: Easy to add new API versions or deprecate old ones
Clean Separation: Clear boundaries between different API capabilities
Type Safety: Full TypeScript support across all client implementations

NPM Scripts

Command	Description
`bun dev`	Run the server in development mode with hot reload
`bun build`	Build the project for production
`bun start`	Start the production server
`bun format`	Format code using Biome
`bun lint`	Lint code using Biome
`bun check`	Run Biome checks on code
`bun typecheck`	Run TypeScript type checking
`bun test`	Run tests
`bun inspect`	Start the MCP Inspector for debugging

🔧 Troubleshooting

NPM Installation Issues

Package Not Found

If you get a "package not found" error:

# Make sure you're using the correct scoped package name
bunx @dsazz/mcp-confluence@latest

# Or try with explicit npm registry
npm install -g @dsazz/mcp-confluence --registry https://registry.npmjs.org

Environment Variables Not Found

If the server fails to start with environment variable errors:

For bunx usage: Create a .env file in your working directory:

# Create .env file in your current directory
echo "CONFLUENCE_HOST_URL=https://your-domain.atlassian.net" > .env
echo "CONFLUENCE_USER_EMAIL=your-email@example.com" >> .env
echo "CONFLUENCE_API_TOKEN=your-api-token" >> .env

For MCP configuration: Set environment variables in your MCP config:

{
  "mcpServers": {
    "Confluence Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-confluence@latest"],
      "env": {
        "CONFLUENCE_HOST_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USER_EMAIL": "your-email@example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

API Connection Issues

Invalid Credentials

Verify your Confluence API token is correct
Ensure your email matches your Atlassian account
Check that your Confluence URL is correct (include https://)

Network/Firewall Issues

Ensure your network allows connections to your Confluence instance
Check if your organization requires VPN access
Verify firewall settings allow outbound HTTPS connections

Development Issues

Build Failures

# Clear dependencies and reinstall
rm -rf node_modules bun.lockb
bun install

# Clean build
rm -rf dist
bun run build

TypeScript Errors

# Run type checking
bun run typecheck

# Check for linting issues
bun run check

📝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Development workflow
Branching strategy
Commit message format
Pull request process
Code style guidelines

📘 Resources

📄 License

_{Built with ❤️ for a better developer experience}