docs: update documentation for features added since v0.20.0 (#1095)

* docs: update documentation for features added since v0.20.0

Cover 9 user-facing changes across 11 files:

New tools: jira_add_issues_to_sprint, confluence_move_page,
confluence_get_page_diff, confluence_reply_to_comment

Enhanced tools: jira_search (page_token), jira_get_field_options
(contains/return_limit/values_only), confluence_search_user (group_name)

Cross-cutting: tool count 68→72 (docs, README, docs.json),
IGNORE_HEADER_AUTH env var, confluence_search_user platform note,
generate_tool_docs.py CATEGORY_TOOLS mapping (incl. watcher tools)

* docs: add one-of constraint warning for confluence_move_page params

At least one of target_parent_id or target_space_key is required;
omitting both raises ValueError. Mark both as No* and add Warning.

Author: sooperset

README.md

@@ -95,7 +95,7 @@ Documentation is also available in [llms.txt format](https://llmstxt.org/), whic
 | `jira_update_issue` - Update issues | `confluence_update_page` - Update pages |
 | `jira_transition_issue` - Change status | `confluence_add_comment` - Add comments |
 
-**65 tools total** — See [Tools Reference](https://mcp-atlassian.soomiles.com/docs/tools-reference) for the complete list.
+**72 tools total** — See [Tools Reference](https://mcp-atlassian.soomiles.com/docs/tools-reference) for the complete list.
 
 ## Security
 

docs.json

@@ -3,7 +3,7 @@
   "theme": "mint",
   "name": "MCP Atlassian",
   "metadata": {
-    "og:description": "MCP server for Atlassian Jira and Confluence — all 68 tools enabled by default"
+    "og:description": "MCP server for Atlassian Jira and Confluence — all 72 tools enabled by default"
   },
   "seo": {
     "indexHiddenPages": false

docs/compatibility.mdx

@@ -122,6 +122,7 @@ MCP Atlassian supports both Atlassian Cloud and Server/Data Center deployments,
 | `jira_get_issue_proforma_forms` | Yes | No | Cloud-only (requires cloud_id for Forms API) |
 | `jira_get_service_desk_queues` | Yes | Yes | Requires Jira Service Management |
 | `confluence_get_page_views` | Yes | No | Cloud-only analytics API |
+| `confluence_search_user` | Yes (CQL) | Yes (group member fallback) | Server/DC uses group member API; specify `group_name` |
 
 ### Content Format Differences
 

docs/configuration.mdx

@@ -155,6 +155,7 @@ This guide covers IDE integration, environment variables, and advanced configura
 | `ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS` | Comma-separated allowed redirect URI patterns for DCR clients |
 | `ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES` | Comma-separated grant types allowed during DCR |
 | `ATLASSIAN_OAUTH_REQUIRE_CONSENT` | Require local consent page before upstream redirect (`true`/`false`) |
+| `IGNORE_HEADER_AUTH` | Bypass proxy-injected auth headers. For GCP Cloud Run, AWS ALB deployments where load balancers inject Authorization headers (`true`/`false`) |
 
 See [.env.example](https://github.com/sooperset/mcp-atlassian/blob/main/.env.example) for all available options.
 

docs/tools-reference.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Tools Reference"
-description: "Overview of all 68 MCP tools for Jira and Confluence — organized by category with quick links"
+description: "Overview of all 72 MCP tools for Jira and Confluence — organized by category with quick links"
 ---
 
-MCP Atlassian provides **68 tools** for interacting with Jira and Confluence. Tools are organized by category below.
+MCP Atlassian provides **72 tools** for interacting with Jira and Confluence. Tools are organized by category below.
 
 ## Jira Tools
 
@@ -66,7 +66,7 @@ Toolsets group related tools for easier management via `TOOLSETS` env var or `--
 | `jira_comments` | Yes | `jira_add_comment`, `jira_edit_comment` |
 | `jira_transitions` | Yes | `jira_get_transitions`, `jira_transition_issue` |
 | `jira_projects` | No | `jira_get_all_projects`, `jira_get_project_versions`, `jira_get_project_components`, `jira_create_version`, `jira_batch_create_versions` |
-| `jira_agile` | No | `jira_get_agile_boards`, `jira_get_board_issues`, `jira_get_sprints_from_board`, `jira_get_sprint_issues`, `jira_create_sprint`, `jira_update_sprint` |
+| `jira_agile` | No | `jira_get_agile_boards`, `jira_get_board_issues`, `jira_get_sprints_from_board`, `jira_get_sprint_issues`, `jira_create_sprint`, `jira_update_sprint`, `jira_add_issues_to_sprint` |
 | `jira_links` | No | `jira_get_link_types`, `jira_link_to_epic`, `jira_create_issue_link`, `jira_create_remote_issue_link`, `jira_remove_issue_link` |
 | `jira_worklog` | No | `jira_get_worklog`, `jira_add_worklog` |
 | `jira_attachments` | No | `jira_download_attachments`, `jira_get_issue_images` |
@@ -81,8 +81,8 @@ Toolsets group related tools for easier management via `TOOLSETS` env var or `--
 
 | Toolset | Core | Tools |
 |---------|:----:|-------|
-| `confluence_pages` | Yes | `confluence_search`, `confluence_get_page`, `confluence_get_page_children`, `confluence_get_page_history`, `confluence_create_page`, `confluence_update_page`, `confluence_delete_page` |
-| `confluence_comments` | Yes | `confluence_get_comments`, `confluence_add_comment` |
+| `confluence_pages` | Yes | `confluence_search`, `confluence_get_page`, `confluence_get_page_children`, `confluence_get_page_history`, `confluence_create_page`, `confluence_update_page`, `confluence_delete_page`, `confluence_move_page`, `confluence_get_page_diff` |
+| `confluence_comments` | Yes | `confluence_get_comments`, `confluence_add_comment`, `confluence_reply_to_comment` |
 | `confluence_labels` | No | `confluence_get_labels`, `confluence_add_label` |
 | `confluence_users` | No | `confluence_search_user` |
 | `confluence_analytics` | No | `confluence_get_page_views` |
@@ -93,7 +93,7 @@ Toolsets group related tools for easier management via `TOOLSETS` env var or `--
 # To restrict to core toolsets plus specific extras:
 TOOLSETS=default,jira_agile,jira_attachments
 
-# Enable all toolsets (68 tools)
+# Enable all toolsets (72 tools)
 TOOLSETS=all
 
 # Command line

docs/tools/confluence-comments.mdx

@@ -26,6 +26,32 @@ Supports Markdown formatting. Comments are added to the page's comment section.
 </Tip>
 
 
+---
+
+### Reply to Comment
+
+Reply to an existing comment thread on a Confluence page.
+
+<Note>This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.</Note>
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `comment_id` | `string` | Yes | The ID of the parent comment to reply to |
+| `body` | `string` | Yes | The reply content in Markdown format |
+
+**Example:**
+
+```json
+{"comment_id": "67890", "body": "Thanks for the feedback! I've updated the section."}
+```
+
+<Tip>
+Get comment IDs from `confluence_get_comments`. Replies are threaded under the parent comment.
+</Tip>
+
+
 ---
 
 ### Get Comments

docs/tools/confluence-pages.mdx

@@ -135,4 +135,61 @@ Get a historical version of a specific Confluence page.
 | `version` | `integer` | Yes | The version number of the page to retrieve |
 | `convert_to_markdown` | `boolean` | No | Whether to convert page to markdown (true) or keep it in raw HTML format (false). Raw HTML can reveal macros (like dates) not visible in markdown, but CAUTION: using HTML significantly increases token usage in AI responses. |
 
+---
+
+### Move Page
+
+Move a Confluence page to a new parent or space.
+
+<Note>This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.</Note>
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | `string` | Yes | ID of the page to move |
+| `target_parent_id` | `string` | No* | Target parent page ID. If omitted with `target_space_key`, moves to space root. |
+| `target_space_key` | `string` | No* | Target space key for cross-space moves |
+| `position` | `string` | No | Position: 'append' (default, move as child of target), 'above' (move before target as sibling), or 'below' (move after target as sibling) |
+
+**Example:**
+
+```json
+{"page_id": "12345678", "target_parent_id": "98765432"}
+```
+
+<Warning>
+At least one of `target_parent_id` or `target_space_key` must be provided.
+</Warning>
+
+<Tip>
+Use `target_space_key` to move pages between spaces. Omit `target_parent_id` with a space key to move to the space root.
+</Tip>
+
+
+---
+
+### Get Page Diff
+
+Get a unified diff between two versions of a Confluence page.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | `string` | Yes | Confluence page ID (numeric ID, can be found in the page URL). For example, in 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title', the page ID is '123456789'. |
+| `from_version` | `integer` | Yes | Source version number (>=1) |
+| `to_version` | `integer` | Yes | Target version number (>=1) |
+
+**Example:**
+
+```json
+{"page_id": "12345678", "from_version": 1, "to_version": 3}
+```
+
+<Tip>
+Use `confluence_get_page_history` to discover available version numbers. The diff is in unified format, showing additions and removals between versions.
+</Tip>
+
+
 ---

docs/tools/confluence-search.mdx

@@ -42,5 +42,10 @@ Search Confluence users using CQL.
 |-----------|------|----------|-------------|
 | `query` | `string` | Yes | Search query - a CQL query string for user search. Examples of CQL: - Basic user lookup by full name: 'user.fullname ~ "First Last"' Note: Special identifiers need proper quoting in CQL: personal space keys (e.g., "~username"), reserved words, numeric IDs, and identifiers with special characters. |
 | `limit` | `integer` | No | Maximum number of results (1-50) |
+| `group_name` | `string` | No | Group to search within on Server/DC instances (default: 'confluence-users'). Ignored on Cloud. |
+
+<Tip>
+On Server/DC, user search falls back to group member enumeration. Use `group_name` to search within a specific group if the default 'confluence-users' doesn't include all users.
+</Tip>
 
 ---

docs/tools/jira-agile.mdx

@@ -121,4 +121,30 @@ Update jira sprint.
 | `end_date` | `string` | No | (Optional) New end date for the sprint |
 | `goal` | `string` | No | (Optional) New goal for the sprint |
 
+---
+
+### Add Issues to Sprint
+
+Add issues to a Jira sprint.
+
+<Note>This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.</Note>
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sprint_id` | `string` | Yes | Sprint ID to add issues to |
+| `issue_keys` | `string` | Yes | Comma-separated issue keys (e.g., 'PROJ-1,PROJ-2') |
+
+**Example:**
+
+```json
+{"sprint_id": "42", "issue_keys": "PROJ-1,PROJ-2,PROJ-3"}
+```
+
+<Tip>
+Get sprint IDs from `jira_get_sprints_from_board`. Issue keys are validated server-side — invalid keys will cause an error.
+</Tip>
+
+
 ---

docs/tools/jira-search-fields.mdx

@@ -17,6 +17,7 @@ Search Jira issues using JQL (Jira Query Language).
 | `start_at` | `integer` | No | Starting index for pagination (0-based) |
 | `projects_filter` | `string` | No | (Optional) Comma-separated list of project keys to filter results by. Overrides the environment variable JIRA_PROJECTS_FILTER if provided. |
 | `expand` | `string` | No | (Optional) fields to expand. Examples: 'renderedFields', 'transitions', 'changelog' |
+| `page_token` | `string` | No | Pagination token from a previous search result. Cloud only — Server/DC uses `start_at` for pagination. |
 **Example:**
 
 ```json
@@ -32,6 +33,10 @@ Always use `ORDER BY` for deterministic results. Use `fields` parameter to limit
 Some JQL functions (e.g., `issueHistory()`) are Cloud-only.
 </Warning>
 
+<Tip>
+Cloud supports cursor-based pagination via `page_token` for deterministic results across large datasets. The token is returned in the `next_page_token` field of search results.
+</Tip>
+
 
 ---
 
@@ -71,5 +76,18 @@ Get allowed option values for a custom field.
 | `context_id` | `string` | No | Field context ID (Cloud only). If omitted, auto-resolves to the global context. |
 | `project_key` | `string` | No | Project key (required for Server/DC). Example: 'PROJ' |
 | `issue_type` | `string` | No | Issue type name (required for Server/DC). Example: 'Bug' |
+| `contains` | `string` | No | Case-insensitive substring filter on option values. Also matches child values in cascading selects. |
+| `return_limit` | `integer` | No | Maximum number of results to return (applied after filtering). |
+| `values_only` | `boolean` | No | If true, return only value strings in a compact JSON format instead of full option objects. |
+
+**Example:**
+
+```json
+{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}
+```
+
+<Tip>
+Use `contains` to filter large option lists (e.g., hundreds of values). Combine with `values_only: true` for a compact response.
+</Tip>
 
 ---