@crypto512/jicon-mcp 0.7.1 → 1.0.0

package/TOOL_LIST.md

@@ -5,43 +5,46 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 42
-- **Jira Tools**: 15
-- **Confluence Tools**: 13
-- **Tempo Tools**: 11
-- **Buffer Tools**: 3
+**Total Tools**: 63
+- **Jira Tools**: 18 (13 read + 5 write)
+- **Confluence Tools**: 17 (11 read + 6 write)
+- **Tempo Tools**: 12 (9 read + 3 write)
+- **Buffer Tools**: 9
+- **Workload Tools**: 2
+- **URL Tools**: 1
+- **Jicon Help Tools**: 1
+- **PlantUML Tools**: 3
 
 **Note**: Tools that return large content use in-memory buffering with pagination support. See the Buffer Tools section for content retrieval.
 
 ---
 
-## Jira Tools (15)
+## Jira Tools (18)
 
 ### 1. jira_search_issues
-**Description**: Search for Jira issues using JQL queries
+**Description**: Search for Jira issues using JQL. Auto-fetches all results (up to 5000).
 **Use Cases**: Find bugs, filter by status, search by assignee, complex queries
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | jql | string | ✓ | JQL query string |
-| maxResults | number | ✗ | Maximum results (default: 50) |
 | fields | string[] | ✗ | Specific fields to return |
 
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
 ---
 
 ### 2. jira_get_issue
-**Description**: Get detailed information about a specific issue with buffered content pagination
+**Description**: Get detailed information about a specific issue
 **Use Cases**: View issue details, check status, read description and comments
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | issueKey | string | ✓ | Issue key (e.g., "PROJ-123") |
 | fields | string[] | ✗ | Specific fields to return |
-| expand | string[] | ✗ | Additional data (e.g., "changelog") |
-| offset | number | ✗ | Character offset to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
+| expand | string[] | ✗ | Additional data (e.g., "changelog", "renderedFields") |
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
@@ -101,15 +104,16 @@ This document provides a comprehensive reference of all available tools in the J
 ---
 
 ### 7. jira_get_issue_comments
-**Description**: Retrieve comments from an issue
+**Description**: Retrieve all comments from a Jira issue
 **Use Cases**: Read discussion history, check updates
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | issueKey | string | ✓ | Issue key |
-| maxResults | number | ✗ | Maximum number of comments |
 | orderBy | string | ✗ | Sort order ("created" or "-created") |
 
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
 ---
 
 ### 8. jira_list_projects
@@ -134,7 +138,19 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-### 10. jira_get_transitions
+### 10. jira_get_issue_types
+**Description**: Get all available issue types in this Jira instance
+**Use Cases**: Discover type names before filtering by type in JQL, find localized or custom type names
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| (none) | | | |
+
+**Tip**: Use this tool FIRST when you need to filter by issue type but don't know exact names. Issue type names may be localized (e.g., "Épopée" instead of "Epic").
+
+---
+
+### 11. jira_get_transitions
 **Description**: Get available workflow transitions for an issue
 **Use Cases**: Check what status changes are possible
 
@@ -144,7 +160,7 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-### 11. jira_link_issues
+### 12. jira_link_issues
 **Description**: Create a link between two issues
 **Use Cases**: Mark blockers, relate issues, create dependencies
 
@@ -157,7 +173,7 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-### 12. jira_get_board
+### 13. jira_get_board
 **Description**: Get Agile board information
 **Use Cases**: View board details, get board configuration
 
@@ -167,8 +183,8 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-### 13. jira_get_sprints
-**Description**: List sprints for an Agile board
+### 14. jira_get_sprints
+**Description**: List all sprints for a board
 **Use Cases**: View active sprints, check sprint schedules
 
 | Parameter | Type | Required | Description |
@@ -176,20 +192,23 @@ This document provides a comprehensive reference of all available tools in the J
 | boardId | number | ✓ | Board ID |
 | state | string | ✗ | Sprint state ("active", "future", "closed") |
 
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
 ---
 
-### 14. jira_get_sprint_issues
-**Description**: Get all issues in a sprint
+### 15. jira_get_sprint_issues
+**Description**: Get all issues in a specific sprint
 **Use Cases**: View sprint backlog, check sprint progress
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | sprintId | number | ✓ | Sprint ID |
-| maxResults | number | ✗ | Maximum number of results |
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
-### 15. jira_get_issue_watchers
+### 16. jira_get_issue_watchers
 **Description**: Get list of watchers on an issue
 **Use Cases**: See who's following an issue
 
@@ -199,102 +218,112 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-## Confluence Tools (13)
+### 17. jira_get_issue_worklogs
+**Description**: Retrieve all worklogs from a Jira issue
+**Use Cases**: Analyze time logged against an issue, see worklog history
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| issueKey | string | ✓ | Issue key (e.g., PROJ-123) |
+
+**Response includes**: `worklogCount`, `totalTimeSpentSeconds`, `totalTimeSpent`, `worklogs`
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
+---
+
+### 18. jira_get_total_worklogs
+**Description**: Get total worklogs for an issue and all its children recursively
+**Use Cases**: Get total time spent on an Epic including all stories and sub-tasks
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| issueKey | string | ✓ | Issue key (e.g., PROJ-123) |
+
+**Response includes**: Breakdown by issue and grand total including:
+- The specified issue
+- All sub-tasks
+- All issues in the Epic (if the issue is an Epic)
+
+---
+
+## Confluence Tools (17)
 
 ### 1. confluence_search_content
-**Description**: Search Confluence content using CQL
+**Description**: Search Confluence content using CQL. Auto-fetches all results (up to 5000).
 **Use Cases**: Find pages, search by keyword, filter by space
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | cql | string | ✓ | CQL query string |
-| limit | number | ✗ | Maximum results (default: 25) |
 | expand | string[] | ✗ | Additional data to expand |
 
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
 ---
 
 ### 2. confluence_get_page
-**Description**: Get a Confluence page by ID with buffered content pagination
-**Use Cases**: Read page content, check version
+**Description**: Get a Confluence page by ID (PREFERRED when you have page ID)
+**Use Cases**: Read page content, prepare for editing
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
-| expand | string[] | ✗ | Additional data (e.g., "body.storage") |
-| offset | number | ✗ | Character offset to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
+| pageId | string | ✓ | Page ID (accepts string or number) |
+| expand | string[] | ✗ | Additional data (e.g., "body.storage", "version") |
+
+**Response includes**: `pageId`, `version`, `bufferId`, `contentSize`, metadata
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, page metadata
+**Usage**: Content is always stored in buffer with `contentType: "xhtml"`. Use `buffer_edit_xhtml` to modify (required for XHTML buffers), then `confluence_draft_create` for user review.
 
 ---
 
 ### 3. confluence_get_page_by_title
-**Description**: Get a page by title and space with buffered content pagination
+**Description**: Get a page by title and space (use ONLY when you don't have page ID)
 **Use Cases**: Find page by name, access documentation
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| spaceKey | string | ✓ | Space key |
+| spaceKey | string | ✓ | Space key (short code like 'MESH', 'TC'), NOT the full space name |
 | title | string | ✓ | Page title |
 | expand | string[] | ✗ | Additional data to expand |
-| offset | number | ✗ | Character offset to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, page metadata
+**Response includes**: `pageId`, `version`, `bufferId`, `contentSize`, metadata
 
----
-
-### 4. confluence_create_page
-**Description**: Create a new Confluence page
-**Use Cases**: Add documentation, create meeting notes
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| spaceKey | string | ✓ | Space key |
-| title | string | ✓ | Page title |
-| content | string | ✓ | Page content (HTML/storage format) |
-| parentId | string | ✗ | Parent page ID |
-| labels | string[] | ✗ | Array of labels |
+**Usage**: Content is always stored in buffer with `contentType: "xhtml"`. Use `buffer_edit_xhtml` to modify (required for XHTML buffers), then `confluence_draft_create` for user review.
 
 ---
 
-### 5. confluence_update_page
-**Description**: Update an existing page
-**Use Cases**: Edit documentation, fix content
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
-| title | string | ✗ | New title |
-| content | string | ✗ | New content |
-| version | number | ✓ | Current version (for locking) |
-| minorEdit | boolean | ✗ | Is this a minor edit |
+> **Note**: All page content changes go through the draft workflow.
+> AI creates/edits drafts; user publishes manually via Confluence UI:
+> - New pages: `confluence_draft_create` → user review → user publishes
+> - Existing pages: `confluence_get_page` → edit → `confluence_draft_create` → user review → user publishes
 
 ---
 
-### 6. confluence_delete_page
+### 4. confluence_delete_page
 **Description**: Delete a Confluence page
 **Use Cases**: Remove outdated content
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
+| pageId | string | ✓ | Page ID (accepts string or number) |
 
 ---
 
-### 7. confluence_list_spaces
-**Description**: List all accessible spaces
+### 5. confluence_list_spaces
+**Description**: List all accessible Confluence spaces
 **Use Cases**: Discover available spaces, get space keys
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| limit | number | ✗ | Maximum number of results |
-| type | string | ✗ | Space type ("global" or "personal") |
+| type | string | ✗ | Space type filter ("global" or "personal") |
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
-### 8. confluence_get_space
-**Description**: Get detailed space information
+### 6. confluence_get_space
+**Description**: Get detailed information about a space
 **Use Cases**: View space details, get homepage
 
 | Parameter | Type | Required | Description |
@@ -304,60 +333,152 @@ This document provides a comprehensive reference of all available tools in the J
 
 ---
 
-### 9. confluence_get_page_children
-**Description**: Get child pages of a page
+### 7. confluence_get_page_children
+**Description**: Get all child pages of a page
 **Use Cases**: Navigate page hierarchy, list subpages
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Parent page ID |
+| pageId | string | ✓ | Parent page ID (accepts string or number) |
 | expand | string[] | ✗ | Additional data to expand |
-| limit | number | ✗ | Maximum number of results |
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
-### 10. confluence_add_comment
-**Description**: Add a comment to a page
+### 8. confluence_add_comment
+**Description**: Add a comment to a Confluence page
 **Use Cases**: Provide feedback, ask questions
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
-| comment | string | ✓ | Comment text (HTML) |
+| pageId | string | ✓ | Page ID (accepts string or number) |
+| comment | string | ✓ | Comment text (HTML format) |
 
 ---
 
-### 11. confluence_get_comments
-**Description**: Get comments on a page
+### 9. confluence_get_comments
+**Description**: Get all comments on a Confluence page
 **Use Cases**: Read feedback, review discussions
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
-| limit | number | ✗ | Maximum number of results |
+| pageId | string | ✓ | Page ID (accepts string or number) |
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
-### 12. confluence_upload_attachment
-**Description**: Upload a file attachment to a page
+### 10. confluence_upload_attachment
+**Description**: Upload an attachment to a Confluence page
 **Use Cases**: Attach documents, upload images
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
+| pageId | string | ✓ | Page ID (accepts string or number) |
 | filePath | string | ✓ | Local file path |
 | comment | string | ✗ | Attachment comment |
 
 ---
 
-### 13. confluence_list_attachments
-**Description**: List attachments on a page
+### 11. confluence_list_attachments
+**Description**: List all attachments on a Confluence page
 **Use Cases**: View uploaded files, check attachments
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| pageId | string | ✓ | Page ID |
-| limit | number | ✗ | Maximum number of results |
+| pageId | string | ✓ | Page ID (accepts string or number) |
+
+Large responses are automatically buffered - use `buffer_get_chunk` or `buffer_grep` to access.
+
+---
+
+### 12. confluence_get_current_user_space
+**Description**: Get the current user's personal Confluence space
+**Use Cases**: Verify personal space before write operations, check space key for write-home restriction
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| (none) | | | |
+
+**Response includes**: `spaceKey`, `spaceName`, `spaceType`, `homePageId`, `homePageTitle`
+
+**Tip**: Use this to find your personal space key when write-home restriction is enabled.
+
+---
+
+### 13. confluence_draft_list
+**Description**: List user's draft pages
+**Use Cases**: View pending drafts, find drafts to continue editing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| spaceKey | string | ✗ | Filter by space key |
+| limit | number | ✗ | Maximum results (default: 25) |
+
+**Response includes**: `drafts` array with `draftId`, `title`, `spaceKey`, `spaceName`, `created`, `url`
+
+---
+
+### 14. confluence_draft_open
+**Description**: Load existing draft into buffer for editing
+**Use Cases**: Continue editing a draft, prepare draft for publishing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| draftId | string | ✓ | Draft page ID |
+
+**Response includes**: `draftId`, `bufferId`, `title`, `spaceKey`, `version`, `url`, `contentPreview`
+
+---
+
+### 15. confluence_draft_create
+**Description**: Create a new server-side draft with local buffer
+**Use Cases**: Start new page as draft, iterative content development
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| spaceKey | string | ✓ | Space key |
+| title | string | ✓ | Draft title |
+| content | string | ✓ | Initial content (storage format) |
+| parentId | string | ✗ | Parent page ID |
+| labels | string[] | ✗ | Array of labels |
+
+**Response includes**: `draftId`, `bufferId`, `title`, `spaceKey`, `version`, `url` (clickable to preview)
+
+**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit_xhtml` with `insert-plantuml` operation.
+
+**Workflow**: Create draft → Click URL to preview → Use `buffer_edit_xhtml` to modify (required for XHTML buffers) → Use `confluence_draft_save` to checkpoint
+
+---
+
+### 16. confluence_draft_save
+**Description**: Save buffer content to draft (delete + recreate pattern)
+**Use Cases**: Checkpoint work, persist edits before publishing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| draftId | string | ✓ | Existing draft ID (will be deleted) |
+| bufferId | string | ✓ | Buffer ID with content to save |
+| title | string | ✗ | Optional new title |
+
+**PlantUML**: Raw @startuml blocks are not supported. Use `buffer_edit_xhtml` with `insert-plantuml` operation.
+
+**Note**: Due to Confluence API limitations, drafts cannot be updated. This tool deletes the old draft and creates a new one with updated content.
+
+**Response includes**: `previousDraftId`, `newDraftId`, `bufferId`, `title`, `url` (new clickable URL)
+
+---
+
+### 17. confluence_draft_delete
+**Description**: Permanently delete a draft
+**Use Cases**: Clean up abandoned drafts, remove unwanted content
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| draftId | string | ✓ | Draft ID to delete |
+
+**Response includes**: `deleted`, `draftId`, `message`
 
 ---
 
@@ -421,10 +542,13 @@ AND lastModified >= now("-30d")
 
 ### Workflow 3: Documentation Update
 1. `confluence_search_content` - Find existing page
-2. `confluence_get_page` - Read current content
-3. `confluence_update_page` - Update content
-4. `confluence_add_comment` - Note changes
-5. `confluence_upload_attachment` - Add supporting files
+2. `confluence_get_page` - Read current content (returns bufferId with `contentType: "xhtml"`)
+3. `buffer_edit_xhtml` - Modify content locally (required for XHTML buffers)
+4. `confluence_draft_create` - Create draft for user review
+5. User reviews draft at URL
+6. User publishes via Confluence UI (click "Publish" button)
+7. `confluence_add_comment` - Note changes
+8. `confluence_upload_attachment` - Add supporting files
 
 ### Workflow 4: Issue Investigation
 1. `jira_get_issue` - Get issue details
@@ -434,6 +558,14 @@ AND lastModified >= now("-30d")
 5. `jira_add_comment` - Document findings
 6. `jira_link_issues` - Link related issues
 
+### Workflow 5: Create Page via Draft
+1. `confluence_draft_create` - Create draft + buffer (with `contentType: "xhtml"`), get preview URL
+2. Click URL to preview draft in browser
+3. `buffer_edit_xhtml` - Modify content locally (required for XHTML buffers)
+4. `confluence_draft_save` - Checkpoint changes, get new URL
+5. Repeat steps 2-4 as needed
+6. User publishes via Confluence UI (click "Publish" button)
+
 ## Tool Selection Guide
 
 ### When to use Jira tools:
@@ -452,23 +584,21 @@ AND lastModified >= now("-30d")
 
 ---
 
-## Tempo Tools (11)
+## Tempo Tools (12)
 
 ### 1. tempo_get_worklogs
-**Description**: Get time tracking worklogs with buffered content pagination
+**Description**: Get Tempo worklogs with filters
 **Use Cases**: View time entries, generate reports, review team work
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | dateFrom | string | ✗ | Start date (YYYY-MM-DD) |
 | dateTo | string | ✗ | End date (YYYY-MM-DD) |
-| projectKey | string | ✗ | Filter by project key |
-| issueKey | string | ✗ | Filter by issue key |
-| workerKey | string | ✗ | Filter by worker username |
-| offset | number | ✗ | Character offset to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
+| projectKey | string | ✗ | Filter by project key (e.g., PROJ) |
+| issueKey | string | ✗ | Filter by issue key (e.g., PROJ-123) |
+| workerKey | string | ✗ | Filter by worker username (get from tempo_get_user_info). Leave empty for ALL worklogs. |
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, worklog metadata
+**WARNING**: No workerKey = returns ALL worklogs. Large responses are buffered.
 
 ---
 
@@ -561,7 +691,7 @@ AND lastModified >= now("-30d")
 ---
 
 ### 10. tempo_get_team_worklogs
-**Description**: Get all worklogs for a team with buffered content pagination
+**Description**: Get all worklogs for a team within a date range
 **Use Cases**: Team capacity reports, sprint reviews
 
 | Parameter | Type | Required | Description |
@@ -569,30 +699,69 @@ AND lastModified >= now("-30d")
 | teamId | number | ✓ | Team ID |
 | dateFrom | string | ✓ | Start date (YYYY-MM-DD) |
 | dateTo | string | ✓ | End date (YYYY-MM-DD) |
-| offset | number | ✗ | Character offset to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, worklog metadata
+Large responses are buffered - use `buffer_get_chunk` or `buffer_grep` to access.
 
 ---
 
 ### 11. tempo_get_user_info
-**Description**: Get current user information (workerKey, accountId, displayName)
+**Description**: Get current user info (workerKey, accountId, displayName)
 **Use Cases**: Get workerKey for filtering worklogs, verify authentication
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | (none) | | | |
 
+**Tip**: Use the `workerKey` value in `tempo_get_worklogs` to filter by user.
+
 ---
 
-## Buffer Tools (3)
+### 12. tempo_get_epic_worklogs
+**Description**: Get all worklogs for an Epic and its child issues in one API call
+**Use Cases**: Epic time tracking, aggregate time reports, sprint cost analysis
 
-Buffer tools are used to retrieve content from buffered responses. When tools like `confluence_get_page` or `jira_get_issue` return large content, they store the full data in an in-memory buffer and return a `bufferId` for pagination.
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| epicKey | string | ✓ | Epic issue key (e.g., PROJ-100) |
+| dateFrom | string | ✗ | Start date filter (YYYY-MM-DD) |
+| dateTo | string | ✗ | End date filter (YYYY-MM-DD) |
 
-### 1. buffer_get_chunk
+**Response includes**: `totalTimeSpent`, `totalWorklogCount`, `issueCount`, breakdown by issue, and full worklog list.
+
+More efficient than `jira_get_total_worklogs` for Tempo instances. Large responses are buffered.
+
+---
+
+## Buffer Tools (9)
+
+Buffer tools are used for local content management. All buffer operations are in-memory - write enforcement is on Jira/Confluence/Tempo tools.
+
+**XHTML Tools**: `buffer_edit_xhtml` and `buffer_validate_xhtml` provide structure-aware editing and validation for Confluence storage format content. XHTML validation is also automatically applied before any Confluence write operation.
+
+### 1. buffer_create
+**Description**: Create a new buffer with initial content
+**Use Cases**: Draft new Confluence pages, prepare content before persisting
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| content | string | ✓ | Initial content for the buffer |
+| metadata | object | ✗ | Optional metadata to attach to the buffer |
+
+**Response includes**: `bufferId`, `totalSize`, `createdAt`, `expiresAt`, `metadata`, `message`
+
+**Example workflow for new page**:
+```typescript
+// 1. buffer_create({ content: "<h1>Title</h1><p></p>" }) -> returns bufferId
+// 2. buffer_edit({ bufferId, old_string: "<p></p>", new_string: "<p>Content</p>" })
+// 3. confluence_draft_create({ spaceKey, title, bufferId }) -> user reviews at URL
+// 4. User publishes via Confluence UI (click "Publish" button)
+```
+
+---
+
+### 2. buffer_get_chunk
 **Description**: Retrieve a chunk of buffered content by buffer ID
-**Use Cases**: Get remaining content from large responses
+**Use Cases**: Get remaining content from large responses, retrieve edited content
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -602,16 +771,9 @@ Buffer tools are used to retrieve content from buffered responses. When tools li
 
 **Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, `metadata`
 
-**Example workflow**:
-```typescript
-// 1. Call confluence_get_page -> returns bufferId, first chunk, hasMore: true
-// 2. Call buffer_get_chunk(bufferId, offset: 5000) -> returns next chunk
-// 3. Repeat until hasMore: false
-```
-
 ---
 
-### 2. buffer_list
+### 3. buffer_list
 **Description**: List all active buffers with their metadata
 **Use Cases**: View active buffers, check expiration times
 
@@ -623,7 +785,7 @@ Buffer tools are used to retrieve content from buffered responses. When tools li
 
 ---
 
-### 3. buffer_clear
+### 4. buffer_clear
 **Description**: Clear a specific buffer or all buffers
 **Use Cases**: Free up memory, clean up after processing
 
@@ -632,3 +794,531 @@ Buffer tools are used to retrieve content from buffered responses. When tools li
 | bufferId | string | ✗ | Buffer ID to clear, or omit to clear all buffers |
 
 **Response includes**: `message`, `cleared` (count of buffers cleared)
+
+---
+
+### 5. buffer_grep
+**Description**: Search buffered content for patterns (regex supported)
+**Use Cases**: Find specific content in large responses, locate text for editing
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to search |
+| pattern | string | ✓ | Regex pattern to search for |
+| -A | number | ✗ | Lines to show after each match |
+| -B | number | ✗ | Lines to show before each match |
+| -C | number | ✗ | Lines to show before AND after |
+| -i | boolean | ✗ | Case insensitive search |
+| -n | boolean | ✗ | Show line numbers (default: true) |
+| output_mode | string | ✗ | "content" or "count" |
+
+**Response includes**: `totalMatches`, `matches` with line numbers and context
+
+---
+
+### 6. buffer_edit
+**Description**: Exact string replacement in buffered content
+**Use Cases**: Modify Jira/Tempo content, fix text in non-XHTML buffers
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID to modify |
+| old_string | string | ✓ | Exact text to replace |
+| new_string | string | ✓ | Replacement text |
+| replace_all | boolean | ✗ | Replace all occurrences (default: false) |
+
+**⚠️ XHTML Buffers Blocked**: This tool is **blocked** for Confluence content (`contentType: "xhtml"`). Use `buffer_edit_xhtml` instead for XHTML buffers.
+
+**Note**: Fails if old_string is not unique (unless replace_all=true). Changes are in-memory only - call update API to persist.
+
+**Response includes**: `success`, `replacements`, `oldSize`, `newSize`
+
+---
+
+### 7. buffer_edit_xhtml
+**Description**: Structure-aware XHTML editing for Confluence storage format
+**Use Cases**: Add table rows, insert PlantUML diagrams, update macros, manipulate page structure
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing XHTML content |
+| operation | string | ✓ | Operation: insert, insert-plantuml, update, update-plantuml, remove, move, wrap |
+| selector | string | ✓ | CSS-like selector for target element(s) |
+| position | string | insert/move | Position: before, after, inside-start, inside-end |
+| content | string | insert/update/wrap | XHTML content for the operation |
+| plantuml | string | plantuml ops | Raw PlantUML code (auto-wrapped and validated) |
+| macroId | string | ✗ | Custom macro ID for PlantUML |
+| attributes | object | update | Attributes to set on element |
+| targetSelector | string | move | Target element for move operation |
+| matchIndex | number | ✗ | Operate on Nth match (0-based) |
+| matchAll | boolean | ✗ | Apply to all matches (default: false) |
+| validate | boolean | ✗ | Validate result (default: true) |
+
+**Selector Syntax**:
+- Tag name: `p`, `table`, `h2`
+- Namespaced: `ac:structured-macro`, `ri:page`
+- Attribute: `[ac:name="plantuml"]`, `ac:structured-macro[ac:name="code"]`
+- Descendant: `table tbody tr`
+- Direct child: `ul > li`
+
+**Example - Add table row**:
+```typescript
+buffer_edit_xhtml({
+  bufferId: "buf_xxx",
+  operation: "insert",
+  selector: "table tbody tr",
+  matchIndex: -1,  // Last row
+  position: "after",
+  content: "<tr><td>New Cell</td></tr>"
+})
+```
+
+**Example - Insert PlantUML diagram**:
+```typescript
+buffer_edit_xhtml({
+  bufferId: "buf_xxx",
+  operation: "insert-plantuml",
+  selector: "h2",
+  matchIndex: 0,
+  position: "after",
+  plantuml: "class User { +name: string }"
+})
+```
+
+---
+
+### 8. buffer_validate_xhtml
+**Description**: Validate buffered content as Confluence storage format (XHTML)
+**Use Cases**: Check content validity before writing, debug validation errors
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing XHTML content |
+
+**Validation Checks**:
+- XML well-formedness (balanced tags, proper nesting)
+- Required attributes on Confluence elements (ac:name, ri:space-key, etc.)
+- Valid layout section types (single, two_equal, etc.)
+- Known macro names (warns for unknown macros)
+
+**Response includes**: `valid`, `errorCount`, `warningCount`, `errors`, `warnings`
+
+**Note**: XHTML validation is automatically applied before Confluence write operations (`confluence_draft_create`, `confluence_draft_save`).
+
+---
+
+### 9. buffer_save_to_file
+**Description**: Save buffer content to a file within the project directory
+**Use Cases**: Export rendered PlantUML diagrams (PNG/EPS), save edited content locally
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing content to save |
+| outputPath | string | ✓ | Output file path (must be within project directory) |
+| decodeBase64 | boolean | ✗ | Decode base64 content before saving (auto-detected for PNG/EPS) |
+
+**Security**: Files can only be saved within the project directory (must contain `.jicon.json`).
+
+**Binary Content**: Base64-encoded content (e.g., from `plantuml_render` with PNG/EPS format) is automatically decoded when `decodeBase64` is true or when the output path ends with `.png` or `.eps`.
+
+**Response includes**: `success`, `path`, `size`, `message`
+
+**Example - Save PlantUML render**:
+```typescript
+// 1. Render diagram to PNG
+const result = plantuml_render({
+  code: "@startuml\nA -> B\n@enduml",
+  format: "png"
+})
+// Returns: { bufferId: "buf_xxx", ... }
+
+// 2. Save to file
+buffer_save_to_file({
+  bufferId: "buf_xxx",
+  outputPath: "./diagrams/sequence.png"
+})
+```
+
+---
+
+## Workload Tools (2)
+
+Utility tools for time calculations. Always available with any Jira, Confluence, or Tempo action.
+
+### 1. workload_convert
+**Description**: Convert workload time between units (seconds, hours, days)
+**Use Cases**: Convert time values for display, calculate work estimates
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| value | number | ✓ | Time value to convert |
+| unit | string | ✓ | Source unit ("seconds", "hours", or "days") |
+| hoursPerDay | number | ✗ | Hours per workday (default: 8) |
+
+**Response includes**: Equivalent values in all units with formatted string
+
+---
+
+### 2. workload_sum
+**Description**: Sum multiple workload values and return total in all units
+**Use Cases**: Calculate total time from multiple entries, aggregate worklogs
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| values | array | ✓ | Array of { value: number, unit: string } |
+| hoursPerDay | number | ✗ | Hours per workday (default: 8) |
+
+**Response includes**: Total in seconds, hours, days, and formatted string
+
+---
+
+## URL Tools (1)
+
+Utility tools for URL construction. Always available with any Jira, Confluence, or Tempo action.
+
+### 1. fullurl
+**Description**: Convert Jira issue keys, Confluence page IDs, or relative paths into full URLs
+**Use Cases**: Generate clickable links for display, resolve relative Confluence paths
+
+**Important**: For local rendering only. Do NOT write resolved full URLs back to Jira/Confluence. Keep relative links in published data to maintain portability.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| input | string | ✓ | Jira issue key, Confluence page ID, or relative path |
+
+**Auto-detection logic**:
+| Input Pattern | Detected Type | Output |
+|---------------|---------------|--------|
+| `PROJ-123` | jira_issue | `{JIRA_URL}/browse/PROJ-123` |
+| `123456` (numeric) | confluence_page_id | `{CONFLUENCE_URL}/pages/viewpage.action?pageId=123456` |
+| `/display/...` | confluence_path | `{CONFLUENCE_URL}/display/...` |
+| `https://...` | full_url | Passthrough (unchanged) |
+
+**Response includes**: `input`, `detectedType`, `service`, `url`
+
+**Examples**:
+```typescript
+fullurl("PROJ-123")           // → https://jira.example.com/browse/PROJ-123
+fullurl("123456")             // → https://confluence.example.com/pages/viewpage.action?pageId=123456
+fullurl("/display/DOCS/Home") // → https://confluence.example.com/display/DOCS/Home
+```
+
+---
+
+## Jicon Help Tools (1)
+
+Unified help system for all Jicon workflows and syntax guides. Always available with any Jira, Confluence, or Tempo action.
+
+### 1. help
+**Description**: Get Jicon MCP Server help - workflows and syntax guides
+**Use Cases**: Learn workflows, understand tool sequences, get syntax references
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| topic | string | ✗ | Topic for detailed help: jql, cql, storage, plantuml |
+
+**Default (no topic)**: Compact workflow guide with decision trees showing:
+- Confluence workflows (create page, update page, draft workflow, search)
+- Jira workflows (search issues, create issue, worklogs)
+- Tempo workflows (log work, get worklogs)
+- Buffer patterns for large responses and editing
+- Utility tools (fullurl, workload_convert)
+- Decision tree for when to call each topic
+
+**Available Topics**:
+
+| Topic | Description |
+|-------|-------------|
+| `jql` | JQL syntax guide - operators, functions, examples |
+| `cql` | CQL syntax guide - search operators, date functions |
+| `storage` | Confluence storage format + structure editing (buffer_edit_xhtml) |
+| `plantuml` | PlantUML syntax for Confluence diagrams |
+
+**Examples**:
+```typescript
+help()                       // Get workflow overview and decision tree
+help(topic="jql")            // JQL syntax guide
+help(topic="storage")        // Basic Confluence formatting
+help(topic="plantuml")       // PlantUML diagram syntax
+```
+
+**Tip**: Start with `help()` to understand the overall workflow, then use specific topics for syntax details.
+
+---
+
+## PlantUML Tools (3)
+
+Docker-based PlantUML validation and rendering. Requires Docker to be installed and running.
+
+**⚠️ External Includes NOT Supported:**
+```
+!include https://raw.githubusercontent.com/...  ← NOT SUPPORTED
+```
+Confluence's PlantUML plugin cannot fetch external URLs. Use native PlantUML syntax instead of C4 includes. See `help(topic="plantuml")` for examples.
+
+### 1. plantuml_validate
+**Description**: Validate PlantUML diagram syntax using a real PlantUML server
+**Use Cases**: Check diagram syntax before inserting into Confluence, debug diagram errors
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| code | string | ✗ | Raw PlantUML code (either code or bufferId required) |
+| bufferId | string | ✗ | Buffer ID containing PlantUML code |
+
+**Response includes**: `valid`, `errors` (array of line-level errors if invalid), `normalized` (normalized code)
+
+**Note**: Validates ALL diagram types (sequence, class, C4, etc.) with line-level error feedback.
+
+---
+
+### 2. plantuml_render
+**Description**: Render PlantUML diagram to a specified format
+**Use Cases**: Generate ASCII art for terminal display, create images for documentation
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| code | string | ✗ | Raw PlantUML code (either code or bufferId required) |
+| bufferId | string | ✗ | Buffer ID containing PlantUML code |
+| format | string | ✗ | Output format: "ascii" (default), "svg", "png", "eps" |
+| maxWidth | number | ✗ | Max width for ASCII output (20-200, default: 80) |
+
+**Response includes**: `bufferId` (for large outputs), `content` (for small outputs), `format`, `size`
+
+**Binary Formats**: PNG and EPS outputs are base64-encoded. Use `buffer_save_to_file` to decode and save to disk.
+
+**Example - ASCII preview**:
+```typescript
+plantuml_render({
+  code: "@startuml\nA -> B: Hello\n@enduml",
+  format: "ascii",
+  maxWidth: 60
+})
+// Returns ASCII art directly in response
+```
+
+**Example - Save PNG**:
+```typescript
+const result = plantuml_render({
+  code: "@startuml\nA -> B\n@enduml",
+  format: "png"
+})
+buffer_save_to_file({
+  bufferId: result.bufferId,
+  outputPath: "./diagram.png"
+})
+```
+
+---
+
+### 3. plantuml_status
+**Description**: Check PlantUML service status
+**Use Cases**: Verify Docker service is running, troubleshoot connection issues
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| (none) | | | |
+
+**Response includes**: `running`, `port`, `containerId`, `message`
+
+**Docker Lifecycle**:
+- Container starts automatically on first `plantuml_validate` or `plantuml_render` call
+- Uses dynamic port allocation (unique per MCP instance)
+- Stops gracefully on MCP server shutdown
+
+---
+
+## AI Integration Guidelines
+
+When using Jicon with AI assistants (Claude, GPT, etc.), follow these patterns for optimal results.
+
+### Content Buffering
+
+Tools that return large content (Confluence pages, Jira issues, Tempo worklogs) use an in-memory buffering system for efficient content pagination.
+
+**How It Works:**
+1. **Initial Call**: When you call a tool like `confluence_get_page`, it fetches the full content and stores it in a buffer
+2. **Chunked Response**: The response includes a `bufferId`, the first chunk of content (default 5000 chars), and pagination info
+3. **Retrieve More**: Use `buffer_get_chunk` with the `bufferId` to get subsequent chunks
+
+**Buffered Response Format:**
+- `bufferId`: Unique identifier for retrieving more content
+- `content`: The current chunk of content
+- `offset`: Starting position of this chunk
+- `limit`: Maximum characters returned
+- `totalSize`: Total size of buffered content
+- `hasMore`: Whether more content is available
+
+**Auto-Buffered Tools:**
+- `confluence_get_page`, `confluence_get_page_by_title`
+- `jira_get_issue`, `jira_search_issues`
+- `tempo_get_worklogs`, `tempo_get_team_worklogs`
+
+**Buffer Management:**
+- **TTL**: Buffers expire after 10 minutes by default; edited buffers reset to 1 day TTL
+- **List Buffers**: Use `buffer_list` to see active buffers
+- **Clear Buffers**: Use `buffer_clear` to free memory
+
+### Buffer Workflows
+
+**Creating new Confluence pages (draft workflow):**
+1. `confluence_draft_create` → creates server draft + buffer, returns clickable preview URL
+2. User clicks URL to review draft in Confluence UI (can edit there)
+3. If changes needed: `confluence_draft_open` → re-reads user's edits into buffer
+4. `buffer_edit_xhtml` → structure-aware editing (or `buffer_edit` for simple text)
+5. `confluence_draft_save` → checkpoint: deletes old draft, creates new with buffer content, returns new URL
+6. Repeat steps 2-5 until user approves
+7. User publishes via Confluence UI (click "Publish" button)
+
+**Editing existing Confluence pages (draft workflow):**
+1. `confluence_get_page` → page content is buffered, returns `bufferId`, `pageId`, and `version`
+2. `buffer_edit_xhtml` → structure-aware editing (tables, macros, layouts)
+3. `confluence_draft_create` → creates draft with modified content for user review
+4. User reviews draft at URL
+5. If changes needed: repeat via `confluence_draft_open` → edit → `confluence_draft_save`
+6. User publishes via Confluence UI (click "Publish" button)
+
+**Saving buffer content to files:**
+- `buffer_save_to_file(bufferId, outputPath)` - Save buffer content to a local file
+- Security: Files can only be saved within project directory (must contain `.jicon.json`)
+- Binary content (PNG/EPS from `plantuml_render`) is auto-decoded from base64
+
+### Buffer Content Types
+
+**Buffer types enforce the correct editing tool:**
+
+| Buffer Source | contentType | Editing Tool |
+|---------------|-------------|--------------|
+| Confluence pages/drafts | `xhtml` | `buffer_edit_xhtml` (required) |
+| Jira issues | `json` | `buffer_edit` |
+| Other content | `plain` | `buffer_edit` |
+
+**XHTML Buffers (Confluence content):**
+- Confluence tools automatically set `contentType: "xhtml"` on buffers
+- `buffer_edit` is **blocked** for XHTML buffers - use `buffer_edit_xhtml` instead
+- This ensures PlantUML validation and proper structure-aware editing
+
+### XHTML Structure Editing
+
+Use `buffer_edit_xhtml` for XML tree-aware editing of Confluence storage format content. This tool provides CSS-like selectors for targeting elements and supports PlantUML diagram insertion with automatic syntax validation.
+
+**Operations:**
+
+| Operation | Description |
+|-----------|-------------|
+| `insert` | Add content relative to selected element |
+| `insert-plantuml` | Insert PlantUML diagram with validation and macro wrapping |
+| `update` | Update element content and/or attributes |
+| `update-plantuml` | Update existing PlantUML macro with validation |
+| `remove` | Delete selected element(s) |
+| `move` | Move element to new location |
+| `wrap` | Wrap element with new parent |
+
+**Selector Syntax:**
+
+```
+p                                    # Tag name
+ac:structured-macro                  # Namespaced element
+[ac:name="plantuml"]                 # Attribute selector
+ac:structured-macro[ac:name="code"]  # Combined tag + attribute
+table tbody tr                       # Descendant selector
+ul > li                              # Direct child selector
+```
+
+**Example - Add Table Row:**
+
+```typescript
+buffer_edit_xhtml({
+  bufferId: "buf_xxx",
+  operation: "insert",
+  selector: "table tbody tr",
+  matchIndex: -1,  // Last row (use 0 for first)
+  position: "after",
+  content: "<tr><td>New Cell 1</td><td>New Cell 2</td></tr>"
+})
+```
+
+**Example - Insert PlantUML Diagram:**
+
+```typescript
+buffer_edit_xhtml({
+  bufferId: "buf_xxx",
+  operation: "insert-plantuml",
+  selector: "h2",
+  matchIndex: 0,
+  position: "after",
+  plantuml: `
+    class User {
+      +id: string
+      +login(): boolean
+    }
+    class Order
+    User --> Order
+  `
+})
+// Automatically wraps in @startuml/@enduml, validates syntax,
+// and generates complete Confluence PlantUML macro
+```
+
+**Position Values:**
+- `before` - Insert before the selected element
+- `after` - Insert after the selected element
+- `inside-start` - Insert as first child of selected element
+- `inside-end` - Insert as last child of selected element
+
+**Match Control:**
+- `matchIndex`: Operate on Nth match (0-based, use negative for reverse)
+- `matchAll`: Apply operation to all matches
+
+**Semantic Positions for PlantUML:**
+
+```typescript
+buffer_edit_xhtml({
+  bufferId: "buf_xxx",
+  operation: "insert-plantuml",
+  semanticPosition: "after-title",  // No selector needed!
+  plantuml: "@startuml\nA -> B: message\n@enduml"
+})
+```
+
+Available: `after-title`, `after-heading`, `before-content`, `end`, `after-toc`
+
+### XHTML Validation
+
+Use `buffer_validate_xhtml` to validate Confluence storage format content:
+
+```typescript
+buffer_validate_xhtml({
+  bufferId: "buf_xxx",
+  validatePlantUml: true  // Enable PlantUML syntax validation (default: true)
+})
+// Returns: { valid: true/false, errors: [...], warnings: [...], plantuml: [...] }
+```
+
+**Validation Checks:**
+- XML well-formedness
+- Required attributes on Confluence elements (ac:name, ri:space-key, etc.)
+- Valid layout section types
+- Known macro names (warnings for unknown macros)
+- PlantUML syntax (if Docker service is running)
+
+**Automatic Validation:**
+XHTML content is automatically validated before Confluence writes (`confluence_draft_create`, `confluence_draft_save`).
+
+### Buffer Lifecycle & Staleness Prevention
+
+**Automatic Invalidation**: When write operations succeed (`confluence_draft_save`, `jira_update_issue`, `tempo_update_worklog`, etc.), any cached buffers for that resource are automatically invalidated.
+
+**Version Conflict Handling**: If a write fails due to a version conflict (HTTP 409), the error includes actionable hints suggesting you re-fetch the resource.
+
+**Resource Tracking**: Read operations attach metadata to buffers (resource type, ID, version) enabling targeted invalidation.
+
+### Confluence Draft Workflow Details
+
+Drafts allow iterative content development with user confirmation before publishing.
+
+**API Limitation:** Confluence Server/Data Center REST API does not support updating drafts. The `confluence_draft_save` tool works around this by:
+1. Deleting the existing draft
+2. Creating a new draft with the updated content
+3. Returning the new draft ID and URL
+
+**Note:** Publishing is done by the user in Confluence UI. The AI creates and manages drafts; the user decides when to publish