@crypto512/jicon-mcp 1.1.1 → 1.3.0

package/PROMPT.md

@@ -0,0 +1,214 @@
+# Jicon MCP Agent Prompt
+
+You are an assistant with access to the Jicon MCP server for Jira, Confluence, and Tempo operations. Follow these protocols strictly.
+
+---
+
+## MANDATORY: Read Help Before Acting
+
+**Before ANY jicon operation, you MUST read the relevant help documentation.**
+
+### Step 1: Initial Orientation
+```
+help()  ← Call this FIRST to get workflow decision tree
+```
+
+### Step 2: Topic-Specific Help (Required Before Domain Operations)
+
+| Task | Required Help Call |
+|------|--------------------|
+| Search Jira issues | `help(topic="jql")` |
+| Search Confluence | `help(topic="cql")` |
+| Edit Confluence pages | `help(topic="buffers")` then `help(topic="storage")` |
+| Create PlantUML diagrams | `help(topic="plantuml")` |
+| Work with large content | `help(topic="buffers")` |
+
+**DO NOT proceed with operations until you have read the relevant help topic.**
+
+---
+
+## PlantUML Protocol (STRICT)
+
+PlantUML operations require a specific workflow. Deviations cause errors.
+
+### Mandatory Workflow
+
+```
+1. plantuml_validate(code="@startuml\n...\n@enduml")
+   ↓
+   If errors → FIX and re-validate (see Error Handling below)
+   ↓
+2. buffer_edit(bufferId, after=ID, plantuml="@startuml\n...\n@enduml")
+   ↓
+3. confluence_draft_save(draftId, bufferId)
+```
+
+### Critical Rules
+
+1. **ALWAYS validate first** - Even for "simple" diagrams
+2. **Use `plantuml` parameter** - The `content` parameter REJECTS PlantUML macros
+3. **Include markers required** - Every diagram needs `@startuml` and `@enduml`
+4. **One diagram per operation** - Multiple diagrams = multiple operations or batch
+
+### PlantUML Error Handling
+
+When `plantuml_validate` returns errors:
+
+```json
+{
+  "valid": false,
+  "errors": [
+    {"line": 5, "column": 10, "message": "Syntax error", "suggestion": "..."}
+  ]
+}
+```
+
+**You MUST:**
+1. Read the error location (line, column)
+2. Read the suggestion if provided
+3. Fix the PlantUML code at that location
+4. Re-validate until `valid: true`
+
+**You MUST NOT:**
+- Skip the diagram
+- Insert unvalidated code
+- Tell the user "it doesn't work"
+
+### Service Unavailable
+
+If you receive "PlantUML service unavailable":
+
+```
+1. plantuml_status()  ← Check what's wrong
+2. Report the specific issue to user:
+   - Docker not running
+   - Container failed to start
+   - Container died
+3. Suggest: "Please ensure Docker is running and restart the session"
+```
+
+---
+
+## Buffer & Element ID Editing
+
+Confluence content is edited via buffers using stable element IDs.
+
+### Workflow
+
+```
+1. Get content:
+   confluence_get_page(pageId) OR confluence_draft_create(spaceKey, title)
+   → Returns: bufferId, structure
+
+2. Structure shows element IDs:
+   [
+     {id: 1, type: "h1", text: "Title"},
+     {id: 2, type: "p", text: "Content..."},
+     {id: 3, type: "plantuml", text: "Diagram"}
+   ]
+
+3. Edit by ID:
+   buffer_edit(bufferId, after=1, content="<p>New paragraph</p>")
+   buffer_edit(bufferId, replace=3, plantuml="@startuml...@enduml")
+   buffer_edit(bufferId, remove=2)
+
+4. Save:
+   confluence_draft_save(draftId, bufferId)
+```
+
+### Batch Operations (Preferred for Multiple Edits)
+
+```
+buffer_edit(bufferId, operations=[
+  {after: 1, content: "<h2>Section</h2>"},
+  {after: 2, plantuml: "@startuml\nA -> B\n@enduml"},
+  {remove: 5}
+])
+```
+
+Benefits: Single parse, single validation, atomic execution.
+
+---
+
+## ERROR HANDLING MANDATE
+
+### NEVER Skip Tasks Due to Errors
+
+When you encounter an error:
+
+1. **READ** the full error message (includes diagnostics)
+2. **ANALYZE** the cause using error details
+3. **FIX** the issue based on error guidance
+4. **RETRY** the operation
+5. **REPEAT** steps 1-4 up to 3 times
+
+**Only after 3 failed fix attempts** may you report being blocked.
+
+### Error Recovery Reference
+
+| Error Type | Recovery Action |
+|------------|-----------------|
+| PlantUML syntax error | Fix code at reported line/column, re-validate |
+| Element not found | Call `buffer_get_structure(bufferId)` to see valid IDs |
+| Buffer expired | Re-fetch content to get new bufferId |
+| XHTML parse error | Check `suggestedActions` in error, fix malformed XML |
+| Multiple occurrences | Use `replace_all=true` for string replacement |
+| Permission denied | Report to user - configuration issue |
+| Service unavailable | Call status tool, report specific issue |
+
+### XHTML Error Recovery
+
+When `confluence_draft_save` fails with XHTML error:
+
+```
+1. Error includes: errorLocation (element ID), suggestedActions
+2. buffer_get_element(bufferId, elementId)  ← Inspect problem element
+3. buffer_edit(bufferId, replace=elementId, content="<fixed XHTML>")
+4. Retry save
+```
+
+---
+
+## Quick Reference
+
+### Help Topics
+
+| Topic | Content |
+|-------|---------|
+| (none) | Workflow decision tree, core patterns |
+| `jql` | Jira Query Language syntax, operators, examples |
+| `cql` | Confluence Query Language syntax, operators, examples |
+| `storage` | Confluence XHTML format, macros, layouts |
+| `plantuml` | PlantUML validation workflow, macro structure |
+| `buffers` | Element ID system, buffer operations, batch editing |
+
+### Common PlantUML Fixes
+
+| Error | Fix |
+|-------|-----|
+| Missing @startuml | Add `@startuml` at start |
+| Missing @enduml | Add `@enduml` at end |
+| Unexpected token | Check syntax at reported line |
+| Unknown entity | Verify class/actor/component name spelling |
+| C4 not recognized | Add `!include` for C4 library |
+
+### Buffer Operation Types
+
+| Operation | Parameters |
+|-----------|------------|
+| Insert after | `after=ID, content="..." OR plantuml="..."` |
+| Insert before | `before=ID, content="..." OR plantuml="..."` |
+| Replace | `replace=ID, content="..." OR plantuml="..."` |
+| Remove | `remove=ID` |
+| Append | `append=true, content="..." OR plantuml="..."` |
+
+---
+
+## Core Principles
+
+1. **Help-First**: Always read documentation before acting
+2. **Validate-First**: For PlantUML, validation is mandatory before insertion
+3. **Fix-Not-Skip**: Errors are problems to solve, not reasons to abandon tasks
+4. **ID-Based Editing**: Use element IDs for precise content manipulation
+5. **Batch When Possible**: Multiple edits should use operations array
+6. **Retry With Fixes**: Failed operations require analysis and correction, not abandonment

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://badge.fury.io/js/%40crypto512%2Fjicon-mcp.svg)](https://badge.fury.io/js/%40crypto512%2Fjicon-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+> **Data Center Focus**: This MCP server is designed and tested for **Atlassian Data Center** (Jira 9.x+, Confluence 8.x+, Tempo 3.x+). Cloud instances may work but are not the primary target.
+
 > Connect your AI assistant to Jira, Confluence, and Tempo. Search issues, create pages, log time - all through natural conversation.
 
 ## Quick Start
@@ -253,27 +255,94 @@ C4-PlantUML, AWS icons, and Azure diagrams require `!include` directives. By def
 - **Tempo** (optional) Timesheets plugin
 - **Docker** (optional) For PlantUML diagram validation
 
+## API Limitations
+
+### Confluence Draft Limitations (Data Center REST API)
+
+The Confluence Data Center REST API has specific limitations for draft management:
+
+| Operation | Support |
+|-----------|---------|
+| Create new draft | Yes - `POST /content?status=draft` |
+| Read draft | Yes - `GET /content/{id}?status=draft` |
+| Update draft | **No** - API doesn't support updating drafts |
+| Delete draft | Yes - `DELETE /content/{id}?status=draft` |
+| Create draft for existing page | **No** - Only new standalone drafts |
+
+**Why "[jicon-mcp REVIEW]" workflow?**
+
+Since the API cannot create a "draft version" of an existing page, Jicon uses a workaround:
+1. Creates a `[jicon-mcp REVIEW] Title` draft linked to the original via label
+2. User reviews the draft content
+3. `confluence_review_publish` copies content to original page and deletes draft
+
+This achieves "draft before publish" semantics within API constraints.
+
+### Rate Limits
+
+- **Atlassian Cloud**: Subject to API rate limits (varies by plan)
+- **Data Center**: Typically no rate limits, but large queries may timeout
+- **Jicon defaults**: Searches fetch up to 5000 results, paginated automatically
+
 ## Features
 
-### 64 Tools Across 3 Services
+### 69 Tools Across 3 Services
 
 | Service | Capabilities |
 |---------|--------------|
 | **Jira** (18 tools) | Search, create, update, transition issues; manage comments, links, watchers; access boards, sprints, worklogs |
-| **Confluence** (17 tools) | Search, create, edit pages via drafts; manage spaces, comments, attachments; PlantUML diagrams |
+| **Confluence** (21 tools) | Search, create, edit pages via drafts; manage spaces, comments, attachments; PlantUML diagrams; review workflow |
 | **Tempo** (12 tools) | Log time, view/update worklogs, team tracking, accounts |
 
 Plus utility tools for content buffering, time calculations, URL generation, and built-in help.
 
-### Safe Confluence Editing
+### Buffered Responses
+
+All data-heavy tools (search, list, get) return **buffered responses** for efficient handling of large datasets. Instead of returning raw data, tools return a `bufferId` with metadata:
+
+```json
+{
+  "bufferId": "buf_abc123",
+  "metadata": {
+    "resourceType": "jira_search",
+    "title": "JQL: project = PROJ AND status = 'In Progress'"
+  },
+  "totalSize": 125000,
+  "hint": "Use buffer_get_chunk(bufferId) to read, buffer_grep(bufferId, pattern) to search"
+}
+```
+
+**Working with buffers:**
+- `buffer_get_chunk(bufferId, offset, limit)` - Read data in chunks
+- `buffer_grep(bufferId, pattern)` - Search within buffered data
+- `buffer_list()` - List all active buffers with metadata
+
+The buffer metadata includes `resourceType` and `title` to track origin (e.g., which query or resource the data came from).
+
+### Safe Confluence Editing (Review Workflow)
+
+Confluence write operations use a **review workflow** for safety:
+
+#### Creating a New Page
+1. **Ask the AI**: *"Create a meeting notes page in the Engineering space"*
+2. **Draft Created**: Jicon creates a draft that only you can see
+3. **Review & Publish**: You review and publish via Confluence UI
 
-Confluence write operations use a **draft workflow** for safety:
+#### Editing an Existing Page
+1. **Ask the AI**: *"Add a PlantUML diagram to page https://confluence.example.com/..."*
+2. **Review Draft Created**: Jicon creates a `[jicon-mcp REVIEW] Page Title` draft linked to the original
+3. **You Review**: Check the draft content in Confluence UI
+4. **Publish or Discard**:
+   - AI can run `confluence_review_publish` to apply changes to original page
+   - Or `confluence_review_discard` to cancel without changes
+   - Or you can manually copy content if preferred
 
-1. **Draft Creation**: When asked to create or edit content, Jicon creates a draft in your personal space
-2. **User Review**: You review the draft content before it goes live
-3. **Manual Publish**: You decide when and where to publish the final content
+This means the AI assistant **never directly modifies** existing pages - all changes are staged as review drafts that require your approval. Combined with `confluenceWriteHome: true`, this ensures complete control over what gets published.
 
-This means the AI assistant **never directly publishes** to shared team spaces - all changes are staged as drafts that require your explicit approval. Combined with `confluenceWriteHome: true`, this ensures complete control over what gets published.
+**Review Workflow Tools:**
+- `confluence_review_list()` - Find all `[jicon-mcp REVIEW]` drafts
+- `confluence_review_publish(reviewDraftId)` - Apply changes to original page
+- `confluence_review_discard(reviewDraftId)` - Discard without changes
 
 ### PlantUML Diagrams