gh-raw-labs-claude-code-marketplace-claude-plugin-plugins-mxcp-plugin/skills/mxcp-expert/assets/project-templates/confluence/README.md

MXCP Confluence Plugin Example

This example demonstrates how to use MXCP with Confluence data. It shows how to:

• Create and use a custom MXCP plugin for Confluence integration
• Query Confluence content using SQL
• Combine Confluence data with other data sources

Overview

The plugin provides several UDFs that allow you to:

• Search pages using keywords and CQL queries
• Fetch page content and metadata
• List child pages and spaces
• Navigate the Confluence content hierarchy

Configuration

1. Creating an Atlassian API Token

Important: This plugin currently only supports API tokens without scopes. While Atlassian has introduced scoped API tokens, there are known compatibility issues when using scoped tokens with basic authentication that this plugin relies on.

To create an API token without scopes:

1. Log in to your Atlassian account at https://id.atlassian.com/manage-profile/security/api-tokens

2. Verify your identity (if prompted):

   • Atlassian may ask you to verify your identity before creating API tokens
   • Check your email for a one-time passcode and enter it when prompted

3. Create the API token:

   • Click "Create API token" (not "Create API token with scopes")
   • Enter a descriptive name for your token (e.g., "MXCP Confluence Integration")
   • Select an expiration date (tokens can last from 1 day to 1 year)
   • Click "Create"

4. Copy and save your token:

   • Click "Copy to clipboard" to copy the token
   • Important: Save this token securely (like in a password manager) as you won't be able to view it again
   • This token will be used as your "password" in the configuration below

2. User Configuration

Add the following to your MXCP user config (~/.mxcp/config.yml). You can use the example config.yml in this directory as a template:

mxcp: 1

projects:
  confluence-demo:
    profiles:
      dev:
        plugin:
          config:
            confluence:
              url: "https://your-domain.atlassian.net/wiki"
              username: "your-email@example.com"
              password: "your-api-token"  # Use the API token you created above

Configuration Notes:

• Replace your-domain with your actual Atlassian domain
• Replace your-email@example.com with the email address of your Atlassian account
• Replace your-api-token with the API token you created in step 1
• The password field should contain your API token, not your actual Atlassian password

2. Site Configuration

Create an mxcp-site.yml file:

mxcp: 1
project: confluence-demo
profile: dev
plugin:
  - name: confluence
    module: mxcp_plugin_confluence
    config: confluence

Available Tools

Search Pages

-- Search for pages containing specific text
SELECT search_pages_confluence($query, $limit) as result;

Get Page

-- Fetch a page's content
SELECT get_page_confluence($page_id) as result;

Get Children

-- List direct children of a page
SELECT get_children_confluence($page_id) as result;

List Spaces

-- List all accessible spaces
SELECT list_spaces_confluence() as result;

Describe Page

-- Show metadata about a page
SELECT describe_page_confluence($page_id) as result;

Example Queries

1. Search and analyze page content:

WITH pages AS (
  SELECT * FROM search_pages_confluence('important documentation', 50)
)
SELECT 
  p.title as page_title,
  p.space.name as space_name,
  p.version.number as version,
  p.metadata.created as created_date
FROM pages p
ORDER BY p.metadata.created DESC;

Plugin Development

The mxcp_plugin_confluence directory contains a complete MXCP plugin implementation that you can use as a reference for creating your own plugins. It demonstrates:

• Plugin class structure
• Type conversion
• UDF implementation
• Configuration handling

Running the Example

1. Set the MXCP_CONFIG environment variable to point to your config file:

   export MXCP_CONFIG=/path/to/examples/confluence/config.yml
   

2. Start the MXCP server:

   mxcp serve
   

Notes

• Make sure to keep your API token secure and never commit it to version control.
• The plugin requires proper authentication and API permissions to work with your Confluence instance.
• All functions return JSON strings containing the requested data.