# MCP Atlassian

A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with Atlassian products (Confluence and Jira).

## Overview

This MCP server allows AI agents to interact with Atlassian products through a standardized interface. It provides extensive tools for:

- **Confluence**: Full CRUD operations, content search, space management, page management, comments, labels, and more using v2 REST API
- **Jira**: Issue management, project operations, transitions, comments, and comprehensive workflow support

## Key Features

- **Modern API Support**: Uses Confluence v2 REST API with fallback to v1 for search functionality
- **Comprehensive Toolset**: 18+ Confluence tools and 8+ Jira tools covering all major operations
- **Security & Privacy**: Built-in PII filtering and SSL verification controls
- **Flexible Configuration**: Support for separate service URLs, authentication methods, and tool filtering
- **Pagination Support**: Cursor-based pagination for v2 APIs and offset/limit for v1 APIs
- **Error Handling**: Comprehensive error handling with detailed error messages
- **Type Safety**: Full TypeScript implementation with proper type definitions

## Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- Atlassian account with API token
- Docker (optional, for containerized deployment)

## Installation

### Standard Installation

1. Clone the repository:

   ```bash
   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   ```

2. Install dependencies:

   ```bash
   npm install
   # or using make
   make install
   ```

3. Create a `.env` file in the root directory with your Atlassian credentials:
   ```
   ATLASSIAN_HOST=https://your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-api-token
   ```

### Docker Installation

1. Clone the repository:

   ```bash
   git clone https://github.com/yourusername/mcp-atlassian.git
   cd mcp-atlassian
   ```

2. Create a `.env` file as described above.

3. Build and run the Docker container:

   ```bash
   # Build the Docker image
   make docker-build

   # Run the Docker container
   make docker-run

   # Or use Docker Compose
   make docker-compose
   ```

## Usage

### Starting the Server

```bash
# Using npm
npm start

# Using make
make start

# Using Docker
make docker-run
```

This will start the MCP server, which will listen and respond on streamable HTTP.

### MCP configuration

```json
    "mcp-searchapi": {
      "name": "mcp-searchapi",
      "type": "streamable-http",
      "streamable": true,
      "url": "http://localhost:3007/mcp"
    }
```

### Available Tools

#### Confluence Tools

**Search & Discovery:**

- **search_confluence**: Search for content in Confluence using v1 API with CQL
  - Parameters: `searchText` (string), `spaceKey` (string, optional), `limit` (number), `start` (number)

- **search_confluence_pages_by_title**: Search pages by title using v2 API
  - Parameters: `title` (string, optional), `spaceId` (string, optional), `limit` (number), `cursor` (string, optional)

**Space Management:**

- **get_confluence_space_by_id_or_key**: Get information about a specific Confluence space
  - Parameters: `spaceIdOrKey` (string)

- **get_confluence_spaces**: Get all available spaces
  - Parameters: `limit` (number, optional), `cursor` (string, optional)

**Page Management:**

- **get_confluence_content**: Get specific page content by ID
  - Parameters: `pageId` (string), `bodyFormat` (enum: storage/atlas_doc_format/wiki, optional)

- **get_confluence_pages**: Get all pages in a space
  - Parameters: `spaceId` (string), `limit` (number, optional), `cursor` (string, optional)

- **get_confluence_child_pages**: Get child pages of a specific page
  - Parameters: `pageId` (string), `limit` (number, optional), `cursor` (string, optional)

- **confluence_create_page**: Create a new Confluence page
  - Parameters: `spaceId` (string), `title` (string), `content` (string), `status` (enum, optional), `representation` (enum, optional), `parentId` (string, optional)

- **confluence_update_page**: Update an existing page
  - Parameters: `pageId` (string), `title` (string), `content` (string), `version` (number), `status` (enum, optional), `representation` (enum, optional), `versionMessage` (string, optional)

- **update_confluence_page_title**: Update only the title of a page
  - Parameters: `pageId` (string), `title` (string), `status` (enum, optional)

- **confluence_delete_page**: Delete a Confluence page
  - Parameters: `pageId` (string)

**Label Management:**

- **get_confluence_pages_by_label**: Find pages with specific labels
  - Parameters: `label` (string), `spaceId` (string, optional), `limit` (number, optional), `cursor` (string, optional)

- **get_confluence_page_labels**: Get labels for a specific page
  - Parameters: `pageId` (string), `limit` (number, optional), `cursor` (string, optional)

- **add_confluence_page_labels**: Add labels to a page
  - Parameters: `pageId` (string), `labels` (array of strings)

**Comments:**

- **get_confluence_page_comments**: Get regular comments on a page
  - Parameters: `pageId` (string), `limit` (number, optional), `cursor` (string, optional)

- **add_confluence_page_comment**: Add a comment to a page
  - Parameters: `pageId` (string), `content` (string), `representation` (enum, optional)

- **get_confluence_page_inline_comments**: Get inline comments on a page
  - Parameters: `pageId` (string), `limit` (number, optional), `cursor` (string, optional)

- **create_confluence_footer_comment**: Create a footer comment
  - Parameters: `pageId` (string, optional), `blogPostId` (string, optional), `parentCommentId` (string, optional), `attachmentId` (string, optional), `customContentId` (string, optional), `content` (string), `representation` (enum, optional)

#### Jira Tools

- **search_jira_issues**: Search for issues using JQL (Jira Query Language)
  - Parameters: `jql` (string), `maxResults` (number, optional)

- **get_jira_issue**: Get detailed information about a specific issue
  - Parameters: `issueKey` (string)

- **jira_get_all_projects**: Get all accessible projects
  - Parameters: none

- **jira_create_issue**: Create a new Jira issue
  - Parameters: `projectKey` (string), `issueType` (string), `summary` (string), `description` (string, optional), additional fields

- **jira_update_issue**: Update an existing issue
  - Parameters: `issueKey` (string), `fields` (object with update data)

- **jira_add_comment**: Add a comment to an issue
  - Parameters: `issueKey` (string), `comment` (string)

- **jira_get_transitions**: Get available transitions for an issue
  - Parameters: `issueKey` (string)

- **jira_transition_issue**: Transition an issue to a different status
  - Parameters: `issueKey` (string), `transitionId` (string), `comment` (string, optional)

## Architecture Notes

### Confluence API Migration

This server primarily uses the **Confluence v2 REST API** for most operations, with strategic fallback to v1 API where necessary:

- **v2 API**: Used for spaces, pages, comments, labels - provides better performance and modern cursor-based pagination
- **v1 API**: Used for content search via CQL - provides more powerful search capabilities
- **SSL Support**: Configurable SSL verification bypass for self-hosted instances
- **Authentication**: Supports basic auth, OAuth 2.0 (planned), and PAT tokens

### Tool Filtering & Security

- **Read-Only Mode**: Disable all write operations for safe exploration
- **Tool Whitelist**: Enable only specific tools via `ENABLED_TOOLS` environment variable
- **PII Filtering**: Automatic detection and masking of sensitive information in responses
- **Error Context**: Detailed error messages without exposing sensitive configuration

## Development

### Project Structure

```
src/
├── config/         # Configuration files
│   └── env.ts      # Environment configuration with validation
├── services/       # Service classes for Atlassian APIs
│   ├── confluencev2.ts    # Confluence v2 REST API service (primary)
│   ├── confluence.ts      # Legacy Confluence service (deprecated)
│   └── jira.ts           # Jira REST API service
├── tools/          # MCP tool implementations
│   ├── search-confluence.ts                    # Content search (v1 API)
│   ├── search-confluence-pages-by-title.ts     # Title search (v2 API)
│   ├── get-confluence-space.ts                 # Single space info
│   ├── get-confluence-spaces.ts                # All spaces list
│   ├── get-confluence-content.ts               # Page content by ID
│   ├── get-confluence-pages.ts                 # Pages in space
│   ├── get-confluence-child-pages.ts           # Child pages
│   ├── get-confluence-pages-by-label.ts        # Pages by label
│   ├── get-confluence-page-labels.ts           # Page labels
│   ├── add-confluence-page-labels.ts           # Add labels
│   ├── get-confluence-page-comments.ts         # Page comments
│   ├── add-confluence-page-comment.ts          # Add comment
│   ├── get-confluence-page-inline-comments.ts  # Inline comments
│   ├── confluence-create-page.ts               # Create page
│   ├── confluence-update-page.ts               # Update page
│   ├── update-confluence-page-title.ts         # Update title only
│   ├── confluence-delete-page.ts               # Delete page
│   ├── create-confluence-footer-comment.ts     # Footer comments
│   ├── search-jira-issues.ts                   # Jira search
│   ├── get-jira-issue.ts                       # Single issue
│   ├── jira-create-issue.ts                    # Create issue
│   ├── jira-update-issue.ts                    # Update issue
│   ├── jira-add-comment.ts                     # Add comment
│   ├── jira-get-transitions.ts                 # Get transitions
│   ├── jira-transition-issue.ts                # Transition issue
│   ├── jira-get-all-projects.ts                # All projects
│   ├── utils.ts                                 # Utility functions & PII filtering
│   └── index.ts                                # Tool exports
├── utils/          # Utility modules
│   └── tool-filter.ts      # Tool filtering and access control
└── index.ts        # Main entry point and server setup
```

### Building

```bash
# Using npm
npm run build

# Using make
make build
```

### Testing

```bash
# Using npm
npm test

# Using make
make test
```

### Makefile Commands

The project includes a Makefile to simplify common operations:

```bash
# Display available commands
make help
```

## License

MIT

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request