# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

npm install -g @aashari/mcp-server-atlassian-confluence

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

# Create a .env file in your project directory
cat > .env ` (required) - API endpoint path
- `-q, --query-params ` (optional) - Query parameters as JSON
- `--jq ` (optional) - JMESPath filter expression
- `-o, --output-format ` (optional) - Output format: `toon` (default) or `json`

**Commands with body (post, put, patch):**
- `-b, --body ` (required) - Request body as JSON

### Examples

## Response Handling

### Large Response Truncation

When API responses exceed approximately 40,000 characters (~10,000 tokens), the server automatically truncates the response to stay within token limits. When this happens:

1. **You'll see a truncation notice** at the end of the response showing:
   - How much of the original response is shown
   - The original response size
   - Guidance on accessing the full data

2. **The full raw response is saved** to a temporary file in `/tmp/mcp/` (path provided in the truncation notice)

3. **Best practices to avoid truncation:**
   - **Always use the `jq` parameter** to filter responses to only needed fields
   - Use `limit` query parameter to restrict result counts (e.g., `{"limit": "5"}`)
   - Request specific resources by ID rather than listing all
   - Use targeted CQL queries for searches

**Example of efficient filtering:**

### Debug Logging

Enable debug logging to see detailed request/response information:

Debug logs are written to: `~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log`

## Testing & Development

### Using MCP Inspector

The MCP Inspector provides a visual interface for testing tools:

Or use the built-in development command if you've cloned the repository:

This starts the server in HTTP mode and opens the inspector UI in your browser.

### HTTP Mode for Testing

You can run the server in HTTP mode to test with curl or other HTTP clients:

The server will listen on `http://localhost:3000/mcp` by default. You can change the port:

**Testing with curl:**

The response comes as Server-Sent Events (SSE) with format:

## Troubleshooting

### "Authentication failed" or "403 Forbidden"

1. **Check your API Token permissions**:
   - Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
   - Make sure your token is still active and hasn't expired

2. **Verify your site name format**:
   - If your Confluence URL is `https://mycompany.atlassian.net`
   - Your site name should be just `mycompany`

3. **Test your credentials**:

### "Resource not found" or "404"

1. **Check the API path**:
   - Paths are case-sensitive
   - Use numeric IDs for spaces and pages (not keys)
   - Verify the resource exists in your browser

2. **Verify access permissions**:
   - Make sure you have access to the space/page in your browser
   - Some content may be restricted to certain users

### "No results found" when searching

1. **Try different search terms**:
   - Use CQL syntax for advanced searches
   - Try broader search criteria

2. **Check CQL syntax**:
   - Validate your CQL in Confluence's advanced search first

### Claude Desktop Integration Issues

1. **Restart Claude Desktop** after updating the config file
2. **Verify config file location**:
   - macOS: `~/.claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Getting Help

If you're still having issues:
1. Run a simple test command to verify everything works
2. Check the [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues) for similar problems
3. Create a new issue with your error message and setup details

## Frequently Asked Questions

### What permissions do I need?

Your Atlassian account needs:
- **Access to Confluence** with the appropriate permissions for the spaces you want to query
- **API token** with appropriate permissions (automatically granted when you create one)

### Can I use this with Confluence Server (on-premise)?

Currently, this tool only supports **Confluence Cloud**. Confluence Server/Data Center support may be added in future versions.

### How do I find my site name?

Your site name is the first part of your Confluence URL:
- URL: `https://mycompany.atlassian.net` -> Site name: `mycompany`
- URL: `https://acme-corp.atlassian.net` -> Site name: `acme-corp`

### What AI assistants does this work with?

Any AI assistant that supports the Model Context Protocol (MCP):
- Claude Desktop
- Cursor AI
- Continue.dev
- Many others

### Is my data secure?

Yes! This tool:
- Runs entirely on your local machine
- Uses your own Confluence credentials
- Never sends your data to third parties
- Only accesses what you give it permission to access

### Can I search across all my spaces at once?

Yes! Use CQL queries for cross-space searches. For example:

## Migration from v2.x

Version 3.0 replaces 8+ specific tools with 5 generic HTTP method tools. If you're upgrading from v2.x:

**Before (v2.x):**

**After (v3.0):**

**Migration examples:**
- `conf_ls_spaces` -> `conf_get` with path `/wiki/api/v2/spaces`
- `conf_get_space` -> `conf_get` with path `/wiki/api/v2/spaces/{id}`
- `conf_ls_pages` -> `conf_get` with path `/wiki/api/v2/pages?space-id={id}`
- `conf_get_page` -> `conf_get` with path `/wiki/api/v2/pages/{id}`
- `conf_search` -> `conf_get` with path `/wiki/rest/api/search?cql=...`
- `conf_add_comment` -> `conf_post` with path `/wiki/api/v2/pages/{id}/footer-comments`

## Technical Details

### Requirements

- **Node.js**: 18.0.0 or higher
- **MCP SDK**: 1.23.0 (uses modern `registerTool` API)
- **Confluence**: Cloud only (Server/Data Center not supported)

### Architecture

This server follows a 5-layer architecture:

1. **Tools Layer** (`src/tools/`) - MCP tool definitions with Zod validation
2. **CLI Layer** (`src/cli/`) - Commander-based CLI for direct testing
3. **Controllers Layer** (`src/controllers/`) - Business logic, JMESPath filtering, output formatting
4. **Services Layer** (`src/services/`) - Confluence API communication
5. **Utils Layer** (`src/utils/`) - Shared utilities (logger, config, formatters, TOON encoder)

### Features

- **Generic HTTP method tools** - Access any Confluence API endpoint
- **TOON output format** - 30-60% token reduction vs JSON
- **JMESPath filtering** - Extract only needed data
- **Response truncation** - Automatic handling of large responses
- **Raw response logging** - Full responses saved to `/tmp/mcp/`
- **Dual transport** - STDIO (for Claude Desktop) and HTTP (for web integrations)
- **Debug logging** - Comprehensive logging for troubleshooting

### Version History

**v3.2.1** (Current)
- Add raw response logging with truncation for large API responses
- Improve dependency compatibility

**v3.2.0**
- Modernize MCP SDK to v1.23.0 with registerTool API

**v3.1.0**
- Add TOON output format for token-efficient LLM responses

**v3.0.0** (Breaking change)
- Replace 8+ domain-specific tools with 5 generic HTTP method tools
- Add JMESPath filtering support
- Full Confluence API access via generic methods

See [CHANGELOG.md](CHANGELOG.md) for complete version history.

## Support

Need help? Here's how to get assistance:

1. **Check the troubleshooting section above** - most common issues are covered there
2. **Visit our GitHub repository** for documentation and examples: [github.com/aashari/mcp-server-atlassian-confluence](https://github.com/aashari/mcp-server-atlassian-confluence)
3. **Report issues** at [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-confluence/issues)
4. **Start a discussion** for feature requests or general questions

---

*Made with care for teams who want to bring AI into their knowledge management workflow.*