@jagadeesh52423/atlassian-mcp-server 1.1.2 → 1.3.0

package/README.md

@@ -1,525 +1,284 @@
-# Atlassian MCP Server
+# 🔗 Atlassian MCP Server
 
 [![npm version](https://badge.fury.io/js/@jagadeesh52423%2Fatlassian-mcp-server.svg)](https://www.npmjs.com/package/@jagadeesh52423/atlassian-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A comprehensive Model Context Protocol (MCP) server that provides AI assistants with access to Atlassian APIs including Jira, Confluence, and Bitbucket. **84 tools** across 3 services — the most complete Atlassian MCP server available.
-
-## Feature Comparison
-
-How we stack up against the official Atlassian MCP server and the popular sooperset/mcp-atlassian:
-
-### Confluence
-
-| Feature | Ours | Official Atlassian | sooperset |
-|---|:---:|:---:|:---:|
-| Search / Get / Create / Update page | YES | YES | YES |
-| Delete page | YES | NO | YES |
-| Get spaces / pages by space | YES | YES | NO |
-| Get child pages | YES | YES | YES |
-| Get/Add comments | YES | YES | YES |
-| **Update/Delete comment** | **YES** | NO | NO |
-| Get/Add/Delete attachments | YES | NO | YES |
-| **Embed image (with positioning)** | **YES** | NO | NO |
-| **Create page with inline images** | **YES** | NO | NO |
-| Get/Add/Remove labels | YES | NO | Partial |
-| **Page version history** | YES | NO | YES |
-
-### Jira
-
-| Feature | Ours | Official Atlassian | sooperset |
-|---|:---:|:---:|:---:|
-| Search/Get/Create/Update issue | YES | YES | YES |
-| Delete issue | YES | NO | YES |
-| Comments (full CRUD) | YES | Partial | Partial |
-| **Smart transition (AI auto-fill)** | **YES** | NO | NO |
-| Attachments (get/add/delete) | YES | NO | NO |
-| Issue links (full CRUD) | YES | NO | Partial |
-| Worklogs (full CRUD) | YES | Partial | Partial |
-| **Watchers (get/add/remove)** | **YES** | NO | NO |
-| **Subtasks (get/create)** | **YES** | NO | NO |
-| **Labels (get/add/remove)** | **YES** | NO | NO |
-| Agile boards & board issues | YES | NO | YES |
-| Sprints (list/create/update) | YES | NO | YES |
-| Sprint issues | YES | NO | YES |
-| Batch create issues | YES | NO | YES |
-| Dev status (PRs/branches/commits) | YES | NO | YES |
-| Issue history | YES | NO | YES |
-| Fields discovery | YES | NO | YES |
-| User lookup by name/email | YES | YES | YES |
-| Issue type metadata | YES | YES | NO |
-| Version/release management | YES | NO | YES |
-| Epic linking | YES | NO | YES |
-
-### Bitbucket
-
-| Feature | Ours | Official Atlassian | sooperset |
-|---|:---:|:---:|:---:|
-| **Full Bitbucket support (16 tools)** | **YES** | NO | NO |
-
-### Key Differentiators
-
-- **Only MCP server covering all 3 Atlassian products** — Confluence + Jira + Bitbucket
-- **Deepest CRUD coverage** — update/delete on comments, worklogs, labels where competitors only do create/read
-- **Smart Field Handling** — AI-driven field suggestions during Jira transitions, unique to this server
-- **Image embedding** — Confluence image embedding with positioning control, unique to this server
-- **84 total tools** vs ~45 (Official) and ~58 (sooperset)
-
-## Features
-
-### Confluence Integration (20 tools)
-- Search pages by text query
-- Get, create, update, and delete pages
-- List spaces and pages within spaces
-- **Child Pages**: Get child pages of a parent page
-- **Page History**: View version history of a page
-- **Attachments**: Add, list, and delete attachments
-- **Comments**: Full CRUD operations on page comments
-- **Labels**: Get, add, and remove labels on pages
-- **Images**: Embed images in page content with positioning control
-- Full support for Confluence storage format
-
-### Jira Integration (48 tools)
-- Search issues by text, filters, or JQL query
-- Get, create, update, and delete issues
-- **Comments**: Full CRUD operations on issue comments
-- **Transitions**: Move issues between statuses with **Smart Field Handling**
-- **Attachments**: Add, list, and delete attachments
-- **Issue Links**: Create and manage links between issues
-- **Worklogs**: Full CRUD for time tracking entries
-- **Watchers**: Manage issue watchers
-- **Subtasks**: Create and list subtasks
-- **History**: View issue change history
-- **Labels**: Get, add, and remove labels on issues
-- **Fields**: Discover available standard and custom fields
-- **Agile**: List boards, get board issues, manage sprints
-- **Sprints**: Create, update, list sprint issues
-- **Versions**: Get, create, and update project versions/releases
-- **Batch Operations**: Bulk create up to 50 issues at once
-- **Dev Status**: View linked PRs, branches, and commits
-- **User Lookup**: Search users by name or email
-- **Issue Types**: Get available issue types per project
-- **Epic Linking**: Link issues to epics (next-gen + classic)
-- List projects
-
-#### Smart Field Handling
-Advanced transition management with intelligent field suggestions:
-- **Contextual Analysis**: Analyzes issue content to provide smart field suggestions
-- **Pattern Recognition**: Recognizes common field patterns (DB scripts, test cases, etc.)
-- **Auto-Suggestions**: Provides context-aware suggestions with reasoning
-- **Enhanced Error Handling**: Returns detailed field information instead of cryptic errors
-
-### Bitbucket Integration (16 tools)
-- List and search repositories
-- Get repository details and create new repositories
-- Manage branches and commits
-- **Pull Requests**: Create, list, and get PR details with diffs
-- **PR Comments**: Full CRUD with resolve/unresolve support
-- Issue tracking within repositories
+An MCP (Model Context Protocol) server that gives AI assistants full access to Jira, Confluence, and Bitbucket Cloud APIs -- 84 tools covering deep CRUD across all three products.
+
+## What It Does
+
+This server acts as a bridge between any MCP-compatible AI client (Claude Desktop, etc.) and your Atlassian Cloud instance. Instead of switching between browser tabs, you ask your AI assistant to search Confluence, create Jira tickets, review pull requests, and more -- all through natural language.
+
+### Key Features
+
+- **Confluence** (20 tools) -- Search, create, read, update, and delete pages. Manage spaces, child pages, comments (full CRUD), attachments, labels, and version history. Input accepts Markdown (auto-converted to ADF); output is native ADF JSON.
+- **Jira** (48 tools) -- Full issue lifecycle: search, CRUD, comments, transitions, attachments, issue links, worklogs, watchers, subtasks, labels, history, agile boards, sprints, versions, batch creation (up to 50 issues), dev status, epic linking, and user lookup.
+- **Bitbucket** (16 tools) -- Repository management, branches, commits, pull requests (create/update/list), PR comments with resolve/unresolve, and issue tracking.
+- **Smart Field Handling** -- AI-driven field suggestions during Jira transitions. Analyzes issue context to auto-suggest values for required fields (e.g., DB scripts, test cases), reducing manual input.
+- **Snapshot Safety Net** -- Automatic local snapshots of mutating operations (create/update/delete) with configurable retention, so you can recover from accidental changes.
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **Atlassian Cloud** account(s) with API tokens
+- An MCP-compatible client (e.g., [Claude Desktop](https://claude.ai/download))
 
 ## Installation
 
-### Option 1: Install from npm (Recommended)
+### From npm (recommended)
 
 ```bash
 npm install -g @jagadeesh52423/atlassian-mcp-server
 ```
 
-Or use with npx without installing:
+Or run without installing:
+
 ```bash
 npx @jagadeesh52423/atlassian-mcp-server
 ```
 
-### Option 2: Install from source
+### From source
 
-1. Clone this repository:
 ```bash
 git clone https://github.com/jagadeeshpulamarasetti/atlassian-mcp-server.git
 cd atlassian-mcp-server
-```
-
-2. Install dependencies:
-```bash
 npm install
-```
-
-3. Build the project:
-```bash
 npm run build
 ```
 
 ## Configuration
 
-1. Copy the environment template:
+### 1. Set environment variables
+
+Copy the template and fill in your credentials:
+
 ```bash
 cp .env.example .env
 ```
 
-2. Fill in your Atlassian credentials in `.env`:
-
 ```env
-# Confluence Configuration
+# Confluence
 CONFLUENCE_DOMAIN=your-domain.atlassian.net
 CONFLUENCE_EMAIL=your-email@example.com
 CONFLUENCE_API_TOKEN=your-confluence-api-token
 
-# Jira Configuration
+# Jira
 JIRA_DOMAIN=your-domain.atlassian.net
 JIRA_EMAIL=your-email@example.com
 JIRA_API_TOKEN=your-jira-api-token
 
-# Optional: OAuth Configuration (for advanced auth)
-JIRA_CLIENT_ID=your-client-id
-JIRA_CLIENT_SECRET=your-client-secret
-
-# Bitbucket Configuration
+# Bitbucket
 BITBUCKET_WORKSPACE=your-workspace
 BITBUCKET_USERNAME=your-username
 BITBUCKET_API_TOKEN=your-bitbucket-api-token
-
-# Legacy: Atlassian Configuration (backward compatibility)
-ATLASSIAN_DOMAIN=your-domain.atlassian.net
-ATLASSIAN_EMAIL=your-email@example.com
-ATLASSIAN_API_TOKEN=your-api-token
 ```
 
-### Getting API Tokens
+You can also set legacy `ATLASSIAN_*` variables as a fallback for Confluence and Jira. Bitbucket always requires its own credentials.
+
+<details>
+<summary>Optional: Jira OAuth and Snapshot settings</summary>
+
+```env
+# Jira OAuth (advanced auth)
+JIRA_CLIENT_ID=your-client-id
+JIRA_CLIENT_SECRET=your-client-secret
+
+# Snapshot safety net (defaults shown)
+MCP_SNAPSHOTS_ENABLED=true
+MCP_SNAPSHOT_DIR=~/.atlassian-mcp-snapshots
+MCP_SNAPSHOT_RETENTION_DAYS=30
+```
 
-#### Atlassian API Token
-1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
-2. Click "Create API token"
-3. Give it a label and create
-4. Copy the token to your `.env` file
+</details>
 
-#### Bitbucket API Token
-1. Go to your Bitbucket settings > Personal access tokens
-2. Create a new API token with required scopes:
-   - Repositories: Read, Write
-   - Issues: Read, Write
-   - Pull requests: Read, Write
-   - Pipelines: Read (if needed)
-3. Copy the token to your `.env` file
+### 2. Get an API token
 
-**Note**: App passwords are deprecated as of September 9, 2025. Use API tokens instead.
+1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **Create API token**, give it a name, and copy the value
+3. For Bitbucket, create a token under **Personal settings > Access tokens** with repo, issue, and PR scopes
 
 ## Usage
 
-### Running the Server
+### Running the server
 
-If installed globally:
 ```bash
+# Global install
 atlassian-mcp-server
-```
 
-If running from source:
-```bash
+# From source
 npm start
-```
 
-For development with auto-reload:
-```bash
+# Development (auto-reload)
 npm run dev
 ```
 
-### Integration with Claude Desktop
+### Claude Desktop integration
 
-Add the following to your Claude Desktop configuration file:
+Add one of the following to your Claude Desktop config:
 
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
 
-#### If installed globally via npm:
 ```json
 {
   "mcpServers": {
     "atlassian": {
-      "command": "atlassian-mcp-server",
+      "command": "npx",
+      "args": ["-y", "@jagadeesh52423/atlassian-mcp-server"],
       "env": {
         "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
         "CONFLUENCE_EMAIL": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-confluence-api-token",
+        "CONFLUENCE_API_TOKEN": "your-token",
         "JIRA_DOMAIN": "your-domain.atlassian.net",
         "JIRA_EMAIL": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-jira-api-token",
+        "JIRA_API_TOKEN": "your-token",
         "BITBUCKET_WORKSPACE": "your-workspace",
         "BITBUCKET_USERNAME": "your-username",
-        "BITBUCKET_API_TOKEN": "your-bitbucket-api-token"
+        "BITBUCKET_API_TOKEN": "your-token"
       }
     }
   }
 }
 ```
 
-#### If using npx:
+<details>
+<summary>Alternative: global install or from-source config</summary>
+
+**Global install:**
 ```json
 {
   "mcpServers": {
     "atlassian": {
-      "command": "npx",
-      "args": ["-y", "@jagadeesh52423/atlassian-mcp-server"],
-      "env": {
-        "CONFLUENCE_DOMAIN": "your-domain.atlassian.net",
-        "CONFLUENCE_EMAIL": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-confluence-api-token",
-        "JIRA_DOMAIN": "your-domain.atlassian.net",
-        "JIRA_EMAIL": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-jira-api-token",
-        "BITBUCKET_WORKSPACE": "your-workspace",
-        "BITBUCKET_USERNAME": "your-username",
-        "BITBUCKET_API_TOKEN": "your-bitbucket-api-token"
-      }
+      "command": "atlassian-mcp-server",
+      "env": { "..." : "same env vars as above" }
     }
   }
 }
 ```
 
-#### If installed from source:
+**From source:**
 ```json
 {
   "mcpServers": {
     "atlassian": {
       "command": "node",
-      "args": ["/path/to/your/atlassian-mcp-server/dist/index.js"]
+      "args": ["/path/to/atlassian-mcp-server/dist/index.js"]
     }
   }
 }
 ```
 
+</details>
+
 ## Available Tools
 
-### Confluence Tools (20 tools)
+### Confluence (20 tools)
 
 | Tool | Description |
 |------|-------------|
-| `confluence_search_pages` | Search pages by text query |
-| `confluence_get_page` | Get specific page by ID |
-| `confluence_create_page` | Create new page with content and optional inline images |
-| `confluence_update_page` | Update existing page |
+| `confluence_search_pages` | Search pages via CQL text query |
+| `confluence_get_page` | Get a page by ID (returns ADF JSON body) |
+| `confluence_create_page` | Create a page (accepts Markdown) |
+| `confluence_update_page` | Update a page (accepts Markdown) |
 | `confluence_delete_page` | Delete a page |
 | `confluence_get_spaces` | List all spaces |
-| `confluence_get_pages_by_space` | Get pages from specific space |
-| `confluence_get_page_children` | Get child pages of a parent page |
+| `confluence_get_pages_by_space` | Get pages in a space |
+| `confluence_get_page_children` | Get child pages |
 | `confluence_get_page_history` | Get page version history |
-| `confluence_get_attachments` | List attachments on a page |
-| `confluence_add_attachment` | Add attachment to a page |
-| `confluence_delete_attachment` | Delete attachment from a page |
-| `confluence_embed_image` | Embed image in page content with positioning |
-| `confluence_get_comments` | Get comments on a page |
-| `confluence_add_comment` | Add comment to a page |
-| `confluence_update_comment` | Update existing comment |
-| `confluence_delete_comment` | Delete comment from a page |
-| `confluence_get_labels` | Get labels on a page |
+| `confluence_get_attachments` | List page attachments |
+| `confluence_add_attachment` | Upload an attachment |
+| `confluence_delete_attachment` | Delete an attachment |
+| `confluence_get_comments` | Get footer and/or inline comments (ADF JSON). `commentType`: `footer` \| `inline` \| `all` (default `all`) |
+| `confluence_add_comment` | Add a comment (Markdown) |
+| `confluence_update_comment` | Update a comment (Markdown) |
+| `confluence_delete_comment` | Delete a comment |
+| `confluence_get_labels` | Get page labels |
 | `confluence_add_labels` | Add labels to a page |
-| `confluence_remove_label` | Remove a label from a page |
-
-### Jira Tools (48 tools)
+| `confluence_remove_label` | Remove a label |
+
+### Jira (48 tools)
+
+| Category | Tools |
+|----------|-------|
+| **Core** | `search_issues`, `get_issue`, `create_issue`, `update_issue`, `delete_issue`, `get_projects`, `get_issue_types`, `get_fields`, `lookup_user` |
+| **Comments** | `add_comment`, `get_comments`, `update_comment`, `delete_comment` |
+| **Transitions** | `get_issue_transitions`, `transition_issue`, `transition_issue_interactive` (smart field handling) |
+| **Attachments** | `get_attachments`, `add_attachment`, `delete_attachment` |
+| **Issue Links** | `get_issue_links`, `create_issue_link`, `delete_issue_link`, `get_link_types` |
+| **Worklogs** | `get_worklogs`, `add_worklog`, `update_worklog`, `delete_worklog` |
+| **Watchers** | `get_watchers`, `add_watcher`, `remove_watcher` |
+| **Subtasks** | `get_subtasks`, `create_subtask` |
+| **Labels** | `get_labels`, `add_labels`, `remove_labels` |
+| **History** | `get_issue_history` |
+| **Agile** | `get_agile_boards`, `get_board_issues`, `get_sprints`, `get_sprint_issues`, `create_sprint`, `update_sprint` |
+| **Versions** | `get_project_versions`, `create_version`, `update_version` |
+| **Batch/Dev** | `batch_create_issues`, `get_dev_status` |
+| **Epic** | `link_to_epic` |
+
+All Jira tools are prefixed with `jira_`.
+
+### Bitbucket (16 tools)
 
 | Tool | Description |
 |------|-------------|
-| **Core** | |
-| `jira_search_issues` | Search issues by text, filters, or JQL |
-| `jira_get_issue` | Get specific issue by key |
-| `jira_create_issue` | Create new issue with custom fields |
-| `jira_update_issue` | Update existing issue |
-| `jira_delete_issue` | Delete issue with optional subtask deletion |
-| `jira_get_projects` | List all projects |
-| `jira_get_issue_types` | Get available issue types for a project |
-| `jira_get_fields` | Discover available standard and custom fields |
-| `jira_lookup_user` | Look up users by name or email |
-| **Comments** | |
-| `jira_add_comment` | Add comment to issue |
-| `jira_get_comments` | Get comments on an issue |
-| `jira_update_comment` | Update existing comment |
-| `jira_delete_comment` | Delete comment from issue |
-| **Transitions** | |
-| `jira_get_issue_transitions` | Get available transitions |
-| `jira_transition_issue` | Change issue status |
-| `jira_transition_issue_interactive` | Change status with smart field handling |
-| **Attachments** | |
-| `jira_get_attachments` | List attachments on an issue |
-| `jira_add_attachment` | Add attachment to issue |
-| `jira_delete_attachment` | Delete attachment from issue |
-| **Issue Links** | |
-| `jira_get_issue_links` | Get linked issues |
-| `jira_create_issue_link` | Create link between issues |
-| `jira_delete_issue_link` | Delete issue link |
-| `jira_get_link_types` | Get available link types |
-| **Worklogs** | |
-| `jira_get_worklogs` | Get work logs on an issue |
-| `jira_add_worklog` | Add work log entry |
-| `jira_update_worklog` | Update work log entry |
-| `jira_delete_worklog` | Delete work log entry |
-| **Watchers** | |
-| `jira_get_watchers` | Get issue watchers |
-| `jira_add_watcher` | Add watcher to issue |
-| `jira_remove_watcher` | Remove watcher from issue |
-| **Subtasks** | |
-| `jira_get_subtasks` | Get subtasks of an issue |
-| `jira_create_subtask` | Create subtask for an issue |
-| **Labels** | |
-| `jira_get_labels` | Get available labels |
-| `jira_add_labels` | Add labels to an issue |
-| `jira_remove_labels` | Remove labels from an issue |
-| **History** | |
-| `jira_get_issue_history` | Get issue change history |
-| **Agile / Sprints** | |
-| `jira_get_agile_boards` | List agile boards with optional filters |
-| `jira_get_board_issues` | Get issues on a board |
-| `jira_get_sprints` | Get sprints for a board |
-| `jira_get_sprint_issues` | Get issues in a sprint |
-| `jira_create_sprint` | Create a new sprint |
-| `jira_update_sprint` | Update sprint (name, state, dates, goal) |
-| **Versions / Releases** | |
-| `jira_get_project_versions` | Get all versions for a project |
-| `jira_create_version` | Create a new version/release |
-| `jira_update_version` | Update version (release, archive, dates) |
-| **Batch & Dev** | |
-| `jira_batch_create_issues` | Bulk create up to 50 issues |
-| `jira_get_dev_status` | Get linked PRs, branches, commits |
-| **Epic** | |
-| `jira_link_to_epic` | Link an issue to an epic |
-
-### Bitbucket Tools (16 tools)
-
-| Tool | Description |
-|------|-------------|
-| `bitbucket_get_repositories` | List repositories in workspace |
-| `bitbucket_get_repository` | Get specific repository details |
-| `bitbucket_create_repository` | Create new repository |
+| `bitbucket_get_repositories` | List workspace repositories |
+| `bitbucket_get_repository` | Get repository details |
+| `bitbucket_create_repository` | Create a repository |
 | `bitbucket_get_pull_requests` | List pull requests |
-| `bitbucket_get_pull_request` | Get specific PR with diff |
-| `bitbucket_create_pull_request` | Create new pull request |
+| `bitbucket_get_pull_request` | Get a PR with diff |
+| `bitbucket_create_pull_request` | Create a pull request |
+| `bitbucket_update_pull_request` | Update a pull request |
 | `bitbucket_get_branches` | List branches |
 | `bitbucket_get_commits` | List commits |
 | `bitbucket_get_issues` | List repository issues |
-| `bitbucket_create_issue` | Create new issue |
+| `bitbucket_create_issue` | Create an issue |
 | `bitbucket_get_pr_comments` | Get PR comments |
-| `bitbucket_add_pr_comment` | Add comment to a PR |
-| `bitbucket_update_pr_comment` | Update PR comment |
-| `bitbucket_delete_pr_comment` | Delete PR comment |
-| `bitbucket_resolve_pr_comment` | Resolve a PR comment |
-| `bitbucket_unresolve_pr_comment` | Unresolve a PR comment |
+| `bitbucket_add_pr_comment` | Add a PR comment |
+| `bitbucket_update_pr_comment` | Update a PR comment |
+| `bitbucket_delete_pr_comment` | Delete a PR comment |
+| `bitbucket_resolve_pr_comment` | Resolve/unresolve a PR comment |
 
-## Example Usage with AI Assistant
-
-```
-User: "Search for pages about API documentation in Confluence"
-AI: Uses confluence_search_pages with query "API documentation"
+## Confluence Content Format (v1.2.0+)
 
-User: "Create a new Jira issue for the bug I found"
-AI: Uses jira_create_issue with appropriate project, summary, and description
+Confluence pages and comments use **ADF (Atlassian Document Format)** natively:
 
-User: "Move this Jira ticket to Code Review status"
-AI: Uses jira_transition_issue_interactive which automatically:
-     - Analyzes the issue content for context
-     - Provides smart suggestions for required fields
-     - Handles transition with minimal user input
-
-User: "What pull requests are open in my main repository?"
-AI: Uses bitbucket_get_pull_requests with your repository name
-
-User: "Create 10 issues for the sprint backlog"
-AI: Uses jira_batch_create_issues to create all at once
-
-User: "Show me the active sprint and its issues"
-AI: Uses jira_get_sprints then jira_get_sprint_issues
-```
+- **Input** -- `create_page`, `update_page`, `add_comment`, `update_comment` accept **Markdown**, which the server converts to ADF using the official `@atlaskit/editor-markdown-transformer`.
+- **Output** -- `get_page`, `get_comments` return ADF JSON (an object, not a string).
+- **Comments** -- `get_comments` returns **both footer (page-level) and inline (text-anchored) comments** by default. Use the `commentType` param (`footer` | `inline` | `all`, default `all`) to filter. Every comment carries a `type` field (`"footer"` or `"inline"`). Inline comments additionally include `anchoredText` (the highlighted page text the comment is attached to), `resolutionStatus` (e.g. `"open"`, `"resolved"`), `markerRef`, and `webuiLink`. _Backwards-compatibility note: callers that previously relied on `get_comments` returning footer comments only will now also receive inline comments under the default `all`; pass `commentType: "footer"` to restore the old footer-only behaviour. The new `type` field is additive and does not remove any existing field._
+- **Inline images** -- Not currently supported via ADF media nodes (requires Atlassian Media API tokens). Use `confluence_add_attachment` instead.
 
-### Smart Field Handling Examples
+## Project Structure
 
-```
-Scenario: Transitioning a template configuration issue
-Issue: "Update notification template to use 'Prefr App'"
-Smart Suggestion: DB Script = "No" (Template changes use MOFU tool)
-                  Test Cases = "No" (Template changes don't require separate tests)
-
-Scenario: Transitioning a new feature development issue
-Issue: "Implement user authentication system"
-Smart Suggestion: DB Script = "Yes" (New features typically need database changes)
-                  Test Cases = "Yes" (New features require comprehensive testing)
-```
-
-## Development
-
-### Project Structure
 ```
 src/
-├── index.ts                # Main MCP server & tool routing
-├── types.ts                # TypeScript interfaces
-├── config.ts               # Configuration management
-├── constants.ts            # Application-wide constants
-├── error-handler.ts        # Structured error handling
-├── clients/
-│   ├── base-client.ts      # Base HTTP client
-│   ├── confluence-client.ts
-│   ├── jira-client.ts
-│   └── bitbucket-client.ts
-├── services/
-│   ├── confluence.ts       # Confluence API service
-│   ├── jira.ts             # Jira API service (with smart field handling)
-│   └── bitbucket.ts        # Bitbucket API service
-├── tools/
-│   ├── index.ts            # Tool aggregation
-│   ├── confluence-tools.ts # Confluence tool definitions
-│   ├── jira-tools.ts       # Jira tool definitions
-│   └── bitbucket-tools.ts  # Bitbucket tool definitions
-└── handlers/
-    ├── confluence-handlers.ts
-    ├── jira-handlers.ts
-    └── bitbucket-handlers.ts
-```
-
-### Building and Testing
-
-```bash
-# Build
-npm run build
-
-# Development with auto-reload
-npm run dev
-
-# Clean build artifacts
-npm run clean
+├── index.ts              # Server entry point and tool routing
+├── config.ts             # Environment variable loading and validation
+├── types.ts              # TypeScript interfaces
+├── constants.ts          # Shared constants
+├── error-handler.ts      # Structured error responses
+├── formatters/           # Markdown-to-ADF and ADF-to-text converters
+├── clients/              # HTTP clients (one per Atlassian product)
+├── services/             # Business logic for each product
+│   └── jira/             # Jira sub-modules (agile, comments, transitions, etc.)
+├── handlers/             # MCP request handlers
+├── tools/                # MCP tool definitions (schemas)
+├── registry/             # Tool dispatch registry
+└── snapshot/             # Snapshot safety net (auto-backup before mutations)
 ```
 
-## Security Considerations
-
-- API tokens are stored in environment variables
-- All API calls use HTTPS
-- Tokens should have minimal required permissions
-- Never commit `.env` files to version control
-
-## Error Handling
-
-The server includes comprehensive error handling:
-- API authentication errors
-- Rate limiting responses
-- Network connectivity issues
-- Invalid parameters
-- Resource not found errors
-- Actionable tips for common issues
-
-## Rate Limiting
-
-Respects Atlassian API rate limits:
-- Jira Cloud: 10 requests per second
-- Confluence Cloud: 10 requests per second
-- Bitbucket Cloud: 1000 requests per hour
-
-## Contributing
+## Security
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests if applicable
-5. Submit a pull request
+- Credentials are read from environment variables only; never committed to source control.
+- All API calls use HTTPS with Basic Auth (base64-encoded `email:token`).
+- Grant tokens the minimum required permissions.
+- Snapshots are stored locally in `~/.atlassian-mcp-snapshots` by default.
 
 ## License
 
-MIT License - see LICENSE file for details
+[MIT](LICENSE)
 
-## Support
+## Links
 
-- **npm package**: [@jagadeesh52423/atlassian-mcp-server](https://www.npmjs.com/package/@jagadeesh52423/atlassian-mcp-server)
-- **Issues & Feature Requests**: [GitHub Issues](https://github.com/jagadeeshpulamarasetti/atlassian-mcp-server/issues)
-- **Source Code**: [GitHub Repository](https://github.com/jagadeeshpulamarasetti/atlassian-mcp-server)
+- **npm:** [@jagadeesh52423/atlassian-mcp-server](https://www.npmjs.com/package/@jagadeesh52423/atlassian-mcp-server)
+- **Source:** [GitHub](https://github.com/jagadeeshpulamarasetti/atlassian-mcp-server)
+- **Issues:** [GitHub Issues](https://github.com/jagadeeshpulamarasetti/atlassian-mcp-server/issues)