Process documentation
", labels=["workflow", "documentation"] ) # Test workflow with OAuth environment workflow = ComplexWorkflow(issue, page) result = workflow.execute() assert result.success assert result.issue_key == "WORKFLOW-123" assert "Workflow Documentation" in result.documentation ``` -------------------------------- ### Integration Testing Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md An example demonstrating integration testing with real Jira and Confluence API clients, including conditional skipping if real data is not available. ```python def test_real_api_integration( jira_integration_client, confluence_integration_client, use_real_jira_data, use_real_confluence_data ): if not use_real_jira_data: pytest.skip("Real Jira data not available") if not use_real_confluence_data: pytest.skip("Real Confluence data not available") # Test with real API clients issues = jira_integration_client.search_issues("project = TEST") pages = confluence_integration_client.get_space_pages("TEST") assert len(issues) >= 0 assert len(pages) >= 0 ``` -------------------------------- ### Recently Modified Content Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/guides/cql-guide.mdx Example query to find pages modified after a specific date, ordered by last modified date. ```cql type = page AND lastModified >= "2024-06-01" ORDER BY lastModified DESC ``` -------------------------------- ### Download Attachments Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-attachments.mdx Example of parameters for downloading attachments from a Jira issue. ```json {"issue_key": "PROJ-123"} ``` -------------------------------- ### Existing Tests Backward Compatibility Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md Shows an example for existing tests, highlighting that they continue to work without changes by using legacy fixtures like `jira_issue_data` and `confluence_page_data`. ```python def test_existing_functionality(jira_issue_data, confluence_page_data): # These fixtures still work as before assert jira_issue_data["key"] == "TEST-123" assert confluence_page_data["title"] == "Test Page" ``` -------------------------------- ### Search Fields Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-search-fields.mdx Example of how to search Jira fields by keyword. ```json {"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"} ``` -------------------------------- ### Search Issues Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-search-fields.mdx Example of how to search Jira issues using JQL and parameters. ```json {"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20} ``` -------------------------------- ### Set up pre-commit hooks Source: https://github.com/sooperset/mcp-atlassian/blob/main/CONTRIBUTING.md Command to install pre-commit hooks. ```sh pre-commit install ``` -------------------------------- ### Update Page Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-pages.mdx Example of how to update an existing Confluence page. ```json {"page_id": "12345678", "title": "Updated Title", "content": "## Updated Content\n\nNew information...", "is_minor_edit": true} ``` -------------------------------- ### Tool Access Control Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools-reference.mdx Example of how to restrict toolsets using the TOOLSETS environment variable or --toolsets flag. ```bash # All toolsets are enabled when TOOLSETS is not set. # To restrict to core toolsets plus specific extras: TOOLSETS=default,jira_agile,jira_attachments ``` -------------------------------- ### Move Page Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-pages.mdx Example of how to move a Confluence page to a new parent. ```json {"page_id": "12345678", "target_parent_id": "98765432"} ``` -------------------------------- ### IDE Configuration with Docker Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/installation.mdx JSON configuration for IDEs to use MCP Atlassian via Docker, including environment variables for Confluence and Jira. ```json { "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "CONFLUENCE_URL", "-e", "CONFLUENCE_USERNAME", "-e", "CONFLUENCE_API_TOKEN", "-e", "JIRA_URL", "-e", "JIRA_USERNAME", "-e", "JIRA_API_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "CONFLUENCE_USERNAME": "your.email@company.com", "CONFLUENCE_API_TOKEN": "your_confluence_api_token", "JIRA_URL": "https://your-company.atlassian.net", "JIRA_USERNAME": "your.email@company.com", "JIRA_API_TOKEN": "your_jira_api_token" } } } } ``` -------------------------------- ### OAuth 2.0 Environment Variables (after setup) Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/authentication.mdx Environment variables for OAuth 2.0 authentication with Jira and Confluence Cloud after setup. ```bash JIRA_URL=https://your-company.atlassian.net CONFLUENCE_URL=https://your-company.atlassian.net/wiki ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_wizard ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_client_id ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_client_secret ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access ``` -------------------------------- ### Test installation Source: https://github.com/sooperset/mcp-atlassian/blob/main/helm/README.md This snippet demonstrates how to test the installation of the Helm chart with specific values set, using the --dry-run and --debug flags. ```bash helm install mcp-atlassian ./mcp-atlassian \ --set confluence.url="https://your-company.atlassian.net/wiki" \ --set confluence.username="user@example.com" \ --set confluence.apiToken="token" \ --set jira.url="https://your-company.atlassian.net" \ --set jira.username="user@example.com" \ --set jira.apiToken="token" \ --dry-run --debug ``` -------------------------------- ### Add Comment Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-comments-worklogs.mdx Example of how to add a comment to a Jira issue. ```json {"issue_key": "PROJ-123", "body": "## Investigation\n\nFound the root cause in module X."} ``` -------------------------------- ### Example Production SLA Configuration Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/advanced/sla-metrics.mdx A typical production configuration for SLA metrics, including metrics selection, working hours, and timezone settings. ```bash # Calculate cycle time and time-in-status JIRA_SLA_METRICS=cycle_time,time_in_status,lead_time # Count only business hours JIRA_SLA_WORKING_HOURS_ONLY=true JIRA_SLA_WORKING_HOURS_START=09:00 JIRA_SLA_WORKING_HOURS_END=17:00 JIRA_SLA_WORKING_DAYS=1,2,3,4,5 # US Eastern timezone JIRA_SLA_TIMEZONE=America/New_York ``` -------------------------------- ### Multi-Service Setup Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/advanced/docker-production.mdx Docker Compose setup for running separate Jira and Confluence MCP Atlassian services. ```yaml version: "3.8" services: jira-mcp: image: ghcr.io/sooperset/mcp-atlassian:latest env_file: .env.jira ports: - "8001:8000" environment: - TRANSPORT=sse - PORT=8000 - TOOLSETS=jira_issues,jira_fields,jira_transitions confluence-mcp: image: ghcr.io/sooperset/mcp-atlassian:latest env_file: .env.confluence ports: - "8002:8000" environment: - TRANSPORT=sse - PORT=8000 - TOOLSETS=confluence_pages,confluence_comments ``` -------------------------------- ### Batch Create Issues Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-issues.mdx Example JSON array for creating multiple Jira issues in a batch, specifying project key, summary, issue type, and optional components. ```json [{"project_key": "PROJ", "summary": "Issue 1", "issue_type": "Task"}, {"project_key": "PROJ", "summary": "Issue 2", "issue_type": "Bug", "components": ["Frontend"]}] ``` -------------------------------- ### Get Page Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-pages.mdx Example of how to get the content of a specific Confluence page by its ID. ```json {"page_id": "12345678", "include_metadata": true} ``` -------------------------------- ### Get Page Diff Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-pages.mdx Example of how to get a diff between two versions of a Confluence page. ```json {"page_id": "12345678", "from_version": 1, "to_version": 3} ``` -------------------------------- ### Transition Issue Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-issues.mdx Example JSON payload for transitioning a Jira issue, including the issue key, transition name, and an optional comment. ```json {"issue_key": "PROJ-123", "transition_name": "Done", "comment": "Closing as completed"} ``` -------------------------------- ### Example Test Structure Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/integration/README.md A Python example demonstrating the structure of a new integration test using pytest, BaseAuthTest, and MockEnvironment. ```python import pytest from tests.utils.base import BaseAuthTest from tests.utils.mocks import MockEnvironment @pytest.mark.integration class TestNewIntegration(BaseAuthTest): def test_feature(self): with MockEnvironment.basic_auth_env(): # Test implementation pass ``` -------------------------------- ### Option 2: Upgrade to Info-Level Logging Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/sigpipe-analysis.mdx Example of upgrading the logging to info-level for when SIGPIPE is not available. ```python logger.info("SIGPIPE not available on this platform (Windows detected)") ``` -------------------------------- ### Manual Cleanup Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/integration/README.md Python code snippet to find test issues using JQL for manual cleanup. ```python # Use JQL to find test issues project = TEST AND summary ~ "Integration Test*" ``` -------------------------------- ### Development Workflow Commands Source: https://github.com/sooperset/mcp-atlassian/blob/main/AGENTS.md Commands for installing dependencies, setting up hooks, running linters and type checkers, and executing the test suite with coverage. ```bash uv sync --frozen --all-extras --dev # install dependencies pre-commit install # setup hooks pre-commit run --all-files # Ruff + mypy uv run pytest -xvs # full test suite uv run pytest tests/unit/ -xvs # unit tests only uv run pytest tests/integration/ # integration tests uv run pytest --cov=src/mcp_atlassian --cov-report=term-missing # coverage ``` -------------------------------- ### Stateless Mode Configuration Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/http-transport.mdx Examples for running MCP Atlassian in stateless mode using uvx, Docker, or environment variables. ```bash # Using uvx uvx mcp-atlassian --transport streamable-http --stateless --port 9000 -vv # Or using Docker docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --stateless --port 9000 -vv # Or via environment variable STATELESS=true uvx mcp-atlassian --transport streamable-http --port 9000 ``` -------------------------------- ### Customized readiness probe configuration Source: https://github.com/sooperset/mcp-atlassian/blob/main/helm/README.md Example of customizing readiness probe values in values.yaml. ```yaml readinessProbe: httpGet: path: /healthz port: http initialDelaySeconds: 15 periodSeconds: 10 timeoutSeconds: 5 failureThreshold: 5 ``` -------------------------------- ### Get Content Attachments Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-attachments.mdx Example JSON payload for listing attachments for a specific Confluence content item, filtering by media type. ```json {"content_id": "12345678", "media_type": "application/octet-stream"} ``` -------------------------------- ### IDE Configuration with uvx (Claude Desktop) Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/installation.mdx Configuration for Claude Desktop to use MCP Atlassian via uvx. This includes setting up environment variables for Confluence and Jira. ```json { "mcpServers": { "mcp-atlassian": { "command": "uvx", "args": ["mcp-atlassian"], "env": { "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "CONFLUENCE_USERNAME": "your.email@company.com", "CONFLUENCE_API_TOKEN": "your_confluence_api_token", "JIRA_URL": "https://your-company.atlassian.net", "JIRA_USERNAME": "your.email@company.com", "JIRA_API_TOKEN": "your_jira_api_token" } } } } ``` -------------------------------- ### Basic Configuration (uvx) Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/configuration.mdx Basic configuration using uvx command. ```json { "mcpServers": { "mcp-atlassian": { "command": "uvx", "args": ["mcp-atlassian"], "env": { "JIRA_URL": "https://your-company.atlassian.net", "JIRA_USERNAME": "your.email@company.com", "JIRA_API_TOKEN": "your_api_token" } } } } ``` -------------------------------- ### Environment Testing Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md Shows how to use parametrized fixtures for testing multiple scenarios, specifically for different authentication environments. ```python @pytest.mark.parametrize("parametrized_auth_env", ["oauth", "basic_auth", "clean"], indirect=True) def test_auth_detection(parametrized_auth_env): # Test with different auth environments detector = AuthDetector() auth_type = detector.detect_auth_type() assert auth_type in ["oauth", "basic", None] ``` -------------------------------- ### Factory Customization Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md Illustrates using factories to create specific test data, showing how to create minimal required data versus using complex, pre-defined data. ```python # Good: Creates minimal required data def test_issue_key_validation(make_jira_issue): issue = make_jira_issue(key="VALID-123") assert validate_key(issue["key"]) # Avoid: Uses complex data when simple would do def test_issue_key_validation(complete_jira_issue_data): assert validate_key(complete_jira_issue_data["key"]) ``` -------------------------------- ### Add Comment Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-comments.mdx Example of how to add a comment to a Confluence page. ```json {"page_id": "12345678", "body": "Great documentation! Consider adding examples for the API section."} ``` -------------------------------- ### Toolset Filtering Command-line Alternative Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/configuration.mdx Command-line alternative for setting toolsets. ```bash uvx mcp-atlassian --toolsets "default,jira_agile" ``` -------------------------------- ### Bring Your Own Token (BYOT) Configuration Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/authentication.mdx Environment variables for Bring Your Own Token (BYOT) authentication. ```bash ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_access_token ``` -------------------------------- ### Search Content Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-search.mdx Example of a JSON payload for searching Confluence content using CQL. ```json {"query": "type=page AND space=DEV AND title~'Architecture'", "limit": 10} ``` -------------------------------- ### Reply to Comment Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-comments.mdx Example of how to reply to an existing comment thread on a Confluence page. ```json {"comment_id": "67890", "body": "Thanks for the feedback! I've updated the section."} ``` -------------------------------- ### Upload Attachment Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/confluence-attachments.mdx Example JSON payload for uploading a single attachment to Confluence content. ```json {"page_id": "12345678", "file_path": "/path/to/diagram.png", "comment": "Updated architecture diagram"} ``` -------------------------------- ### Factory-Based Fixture Usage Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md Shows how to use a factory-based fixture to create customizable test data, allowing specific properties like issue keys and field values to be defined. ```python def test_custom_issue(make_jira_issue): issue = make_jira_issue( key="CUSTOM-123", fields={"priority": {"name": "High"}} ) assert issue["key"] == "CUSTOM-123" assert issue["fields"]["priority"]["name"] == "High" ``` -------------------------------- ### Add Issues to Sprint Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-agile.mdx Example of how to add issues to a Jira sprint using JSON payload. ```json {"sprint_id": "42", "issue_keys": "PROJ-1,PROJ-2,PROJ-3"} ``` -------------------------------- ### Enable All Toolsets Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools-reference.mdx Enables all available toolsets for MCP-Atlassian. ```bash # Enable all toolsets (72 tools) TOOLSETS=all # Command line uvx mcp-atlassian --toolsets "default,jira_agile" ``` -------------------------------- ### Tool Filtering Command-line Alternative Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/configuration.mdx Command-line alternative for enabling specific tools. ```bash uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue" ``` -------------------------------- ### GitHub Copilot MCP Server Configuration with Docker Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/compatibility.mdx Configuration for running mcp-atlassian via Docker for GitHub Copilot, exposing via stdio. ```json { "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "JIRA_URL=https://your-instance.atlassian.net", "-e", "JIRA_USERNAME=your-email@example.com", "-e", "JIRA_API_TOKEN=your-api-token", "ghcr.io/sooperset/mcp-atlassian:latest" ] } } } ``` -------------------------------- ### Update Issue Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/tools/jira-issues.mdx Example JSON payload for updating a Jira issue, including basic fields and additional fields like priority. ```json {"issue_key": "PROJ-123", "summary": "Updated title", "description": "New description", "additional_fields": "{\"priority\": {\"name\": \"High\"}}"} ``` -------------------------------- ### Session-Scoped Data Example Source: https://github.com/sooperset/mcp-atlassian/blob/main/tests/README.md Demonstrates the use of session-scoped fixtures for data that doesn't change, contrasting it with creating new data on every test run. ```python # Good: Uses session-scoped data def test_field_parsing(session_jira_field_definitions): parser = FieldParser(session_jira_field_definitions) assert parser.is_valid() # Avoid: Creates new data every time def test_field_parsing(): fields = create_field_definitions() # Expensive operation parser = FieldParser(fields) assert parser.is_valid() ``` -------------------------------- ### Docker with Environment File Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/configuration.mdx Configuration for running MCP Atlassian with Docker using an environment file. ```json { "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "--env-file", "/path/to/your/mcp-atlassian.env", "ghcr.io/sooperset/mcp-atlassian:latest" ] } } } ``` -------------------------------- ### View Logs on macOS Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/troubleshooting.mdx Command to tail log files on macOS. ```bash tail -n 20 -f ~/Library/Logs/Claude/mcp*.log ``` -------------------------------- ### Cross-Project Search Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/guides/jql-guide.mdx Finds issues in multiple specified projects that are currently in progress. ```jql project IN ("PROJ", "DEVOPS", "INFRA") AND status = "In Progress" ``` -------------------------------- ### Sprint Planning - Get the board and active sprint Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/guides/common-workflows.mdx Retrieves Scrum boards for a project. ```json { "jira_get_agile_boards": {"project_key": "PROJ", "board_type": "scrum"} } ``` -------------------------------- ### View Logs on Windows Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/troubleshooting.mdx Command to view log files on Windows. ```cmd type %APPDATA%\Claude\logs\mcp*.log | more ``` -------------------------------- ### Get SLA Metrics for an Issue Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/advanced/sla-metrics.mdx Request SLA metrics for a specific Jira issue. ```json jira_get_issue_sla: { "issue_key": "PROJ-123", "metrics": "cycle_time,time_in_status,lead_time" } ``` -------------------------------- ### Server/Data Center Configuration Source: https://github.com/sooperset/mcp-atlassian/blob/main/docs/configuration.mdx Configuration for Server/Data Center environments. ```json { "mcpServers": { "mcp-atlassian": { "command": "uvx", "args": ["mcp-atlassian"], "env": { "JIRA_URL": "https://jira.your-company.com", "JIRA_PERSONAL_TOKEN": "your_pat", "JIRA_SSL_VERIFY": "false", "CONFLUENCE_URL": "https://confluence.your-company.com", "CONFLUENCE_PERSONAL_TOKEN": "your_pat", "CONFLUENCE_SSL_VERIFY": "false" } } } } ```