MCP Atlassian Integration

Warnings

• gotcha Configuration for `mcp-atlassian` relies heavily on specific environment variables (e.g., `ATLASSIAN_SUBDOMAIN`, `ATLASSIAN_API_TOKEN`, `CONFLUENCE_SPACE_ID`). Incorrectly set or missing variables are the most common source of runtime errors.
  Fix: Ensure all required environment variables are correctly defined in your shell environment or provided via a `.env` file (which `python-dotenv` can load automatically) before running the application or initializing components.
• gotcha The library is primarily designed to function as a standalone service or CLI (`mcp-atlassian run-server` or `mcp-atlassian cli`). While individual core components can be imported, their setup and expected operational context often assume the environment is configured as if running the full service, which might not be immediately intuitive for direct programmatic embedding.
  Fix: For most use cases, it's recommended to interact with the library via its provided CLI or server commands. If programmatic embedding is required, carefully review the official documentation and source code to understand component dependencies and expected environment setup.
• breaking As a pre-1.0 library (currently `0.21.1`), `mcp-atlassian` does not guarantee strict semantic versioning. Breaking changes to API interfaces, configuration schemas, or core logic may be introduced in minor version increments (e.g., `0.x.y` to `0.x+1.z`).
  Fix: Pin your `mcp-atlassian` dependency to a specific version (e.g., `mcp-atlassian==0.21.1`) and thoroughly review the release notes or GitHub commit history for any breaking changes when planning an upgrade to a newer minor version.

Install

• pip install mcp-atlassian Install stable version

Imports

• AtlassianConfig

  from mcp_atlassian.config import AtlassianConfig

• AtlassianConfigSchema

  from mcp_atlassian.config import AtlassianConfigSchema

• AtlassianContextManager

  from mcp_atlassian.lib.atlassian_context_manager import AtlassianContextManager

Quickstart

This quickstart demonstrates how to programmatically load the `mcp-atlassian` configuration from environment variables and initialize the `AtlassianContextManager`. It showcases the core configuration and component setup, which is essential for any interaction with the library. Note that actual Atlassian API calls would require valid credentials and specific method calls on the `context_manager` object.

import os
from mcp_atlassian.config import AtlassianConfig, AtlassianConfigSchema
from mcp_atlassian.lib.atlassian_context_manager import AtlassianContextManager

# Set dummy environment variables for demonstration/validation.
# In a real scenario, these would be loaded from your shell environment or a .env file.
os.environ['ATLASSIAN_SUBDOMAIN'] = os.environ.get('ATLASSIAN_SUBDOMAIN', 'your-subdomain')
os.environ['ATLASSIAN_USERNAME'] = os.environ.get('ATLASSIAN_USERNAME', 'email@example.com')
os.environ['ATLASSIAN_API_TOKEN'] = os.environ.get('ATLASSIAN_API_TOKEN', 'your-api-token')
os.environ['CONFLUENCE_SPACE_ID'] = os.environ.get('CONFLUENCE_SPACE_ID', 'YOURSPACE')
os.environ['JIRA_PROJECT_KEY'] = os.environ.get('JIRA_PROJECT_KEY', 'YOURPROJ')

try:
    # Load configuration from environment variables
    config: AtlassianConfig = AtlassianConfigSchema().load(os.environ)
    print("Configuration loaded successfully.")
    print(f"Atlassian Subdomain: {config.atlassian_subdomain}")

    # Initialize the Atlassian Context Manager
    # This step demonstrates setup but will require valid credentials for actual API calls.
    context_manager = AtlassianContextManager(config)
    print("AtlassianContextManager initialized.")
    # To perform an actual operation, you would use methods like:
    # confluence_doc = context_manager.get_confluence_document('page-title')
    # jira_issue = context_manager.get_jira_issue('JIRA-123')

except Exception as e:
    print(f"Error loading configuration or initializing: {e}")
    print("Please ensure all required ATLASSIAN_* environment variables are set correctly.")