@crypto512/jicon-mcp 1.3.0 → 2.1.0

package/PROMPT.md

@@ -1,214 +1,33 @@
 # 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.
+You are an assistant with access to the Jicon MCP server for Jira, Confluence, and Tempo operations.
 
----
+## Before ANY Operation: Call Help
 
-## MANDATORY: Read Help Before Acting
+**Always start by reading the help documentation:**
 
-**Before ANY jicon operation, you MUST read the relevant help documentation.**
-
-### Step 1: Initial Orientation
 ```
-help()  ← Call this FIRST to get workflow decision tree
+help()  ← Returns workflow decision tree and quick reference
 ```
 
-### Step 2: Topic-Specific Help (Required Before Domain Operations)
+Then use topic-specific help for your task:
 
-| Task | Required Help Call |
-|------|--------------------|
-| Search Jira issues | `help(topic="jql")` |
+| Task | Help Command |
+|------|--------------|
+| Search Jira | `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"}
-   ]
+| PlantUML diagrams | `help(topic="plantuml")` |
 
-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
+## Available 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
+| `jql` | Jira Query Language syntax |
+| `cql` | Confluence Query Language syntax |
+| `storage` | Confluence XHTML format |
+| `plantuml` | PlantUML validation workflow |
+| `buffers` | Element ID system, buffer operations |
 
-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
+The help system provides complete guidance for all operations. Read it before proceeding.

package/README.md

@@ -1,5 +1,13 @@
 # Jicon - Jira & Confluence MCP Server
 
+<!--
+  README.md Guidelines:
+  - Keep this file USER-FOCUSED: describe features and benefits, not implementation details
+  - NO tool names, function signatures, or technical API details here
+  - Tool documentation belongs in TOOL_LIST.md
+  - Development documentation belongs in CLAUDE.md
+-->
+
 [![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)
 
@@ -23,9 +31,11 @@ Once configured, just ask in natural language:
 
 ### Jira
 - *"Find all high-priority bugs assigned to me"*
+- *"What happened on project ACME this week?"* (Activity digest)
 - *"Create a task for implementing user authentication"*
 - *"Move PROJ-123 to Done and add a comment that it's deployed"*
 - *"Show me the current sprint's progress"*
+- *"Summarize recent discussions about authentication"* (Comment analysis)
 - *"Link PROJ-456 as blocking PROJ-789"*
 
 ### Confluence
@@ -110,65 +120,61 @@ Add to `opencode.jsonc` in your project root or `~/.config/opencode/opencode.jso
 
 ## Configuration
 
+All configuration is done through environment variables.
+
 ### Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `JIRA_URL` | Your Jira instance URL |
-| `JIRA_USERNAME` | Your email (omit for Data Center PAT) |
-| `JIRA_API_TOKEN` | API token or Personal Access Token |
-| `JIRA_AUTH_TYPE` | Optional: `basic` or `bearer` (auto-detected from username) |
-| `CONFLUENCE_URL` | Your Confluence instance URL |
-| `CONFLUENCE_USERNAME` | Your email (omit for Data Center PAT) |
-| `CONFLUENCE_API_TOKEN` | API token or Personal Access Token |
-| `CONFLUENCE_AUTH_TYPE` | Optional: `basic` or `bearer` (auto-detected from username) |
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `JIRA_URL` | string | - | Jira instance URL |
+| `JIRA_USERNAME` | string | - | Email (omit for Data Center PAT) |
+| `JIRA_API_TOKEN` | string | - | API token or Personal Access Token |
+| `JIRA_AUTH_TYPE` | `basic`\|`bearer` | auto | Auth type (auto-detected from username) |
+| `CONFLUENCE_URL` | string | - | Confluence instance URL |
+| `CONFLUENCE_USERNAME` | string | - | Email (omit for Data Center PAT) |
+| `CONFLUENCE_API_TOKEN` | string | - | API token or Personal Access Token |
+| `CONFLUENCE_AUTH_TYPE` | `basic`\|`bearer` | auto | Auth type (auto-detected from username) |
+| `JICON_PERMISSIONS_MODE` | `readonly`\|`full`\|`custom` | `readonly` | Permission mode |
+| `JICON_PERMISSIONS_WHITELIST` | comma-separated | - | Tools to allow (custom mode) |
+| `JICON_PERMISSIONS_BLACKLIST` | comma-separated | - | Tools to deny (custom mode) |
+| `JICON_CONFLUENCE_WRITE_HOME` | `true`\|`false` | `false` | Restrict Confluence writes to personal space |
+| `JICON_PLANTUML_SERVER_URL` | string | - | PlantUML server URL (e.g., `http://localhost:8080`) |
+| `JICON_MAX_OUTPUT` | number | `16000` | Maximum output characters |
 
 **Note:** Tempo uses the same Jira credentials - no separate configuration needed.
 
-### Configuration File (Optional)
+### Permission Modes
 
-Create `.jicon.json` in your project root for project-specific settings, or `~/.config/jicon/jicon.json` for user-wide settings:
+Control what operations are allowed. **By default, Jicon runs in read-only mode** - all read tools across Jira, Confluence, and Tempo are available, but no write operations.
 
+**Read-Only** (default):
 ```json
 {
-  "jira": {
-    "url": "https://jira.example.com",
-    "username": "your-email@example.com",
-    "token": "your-api-token"
-  },
-  "confluence": {
-    "url": "https://confluence.example.com",
-    "username": "your-email@example.com",
-    "token": "your-api-token"
+  "env": {
+    "JIRA_URL": "https://jira.example.com",
+    "JIRA_API_TOKEN": "your-token"
   }
 }
 ```
 
-**Priority:** Project config → User config → Environment variables
-
-**Important:** Add `.jicon.json` to your `.gitignore`!
-
-### Permission Modes
-
-Control what operations are allowed. **By default, Jicon runs in read-only mode** - all read tools across Jira, Confluence, and Tempo are available, but no write operations. Safe for exploration without risk of accidental modifications.
-
-**Read-Only** (default) - all read tools enabled:
+**Full Access**:
 ```json
-{ "permissions": { "mode": "readonly" } }
-```
-
-**Full Access** - all operations enabled:
-```json
-{ "permissions": { "mode": "full" } }
+{
+  "env": {
+    "JIRA_URL": "https://jira.example.com",
+    "JIRA_API_TOKEN": "your-token",
+    "JICON_PERMISSIONS_MODE": "full"
+  }
+}
 ```
 
-**Custom** - fine-grained control with whitelist and blacklist:
+**Custom** - fine-grained control:
 ```json
 {
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_all", "confluence_all", "tempo_all"],
-    "blacklist": ["confluence_delete_page", "tempo_delete_worklog"]
+  "env": {
+    "JICON_PERMISSIONS_MODE": "custom",
+    "JICON_PERMISSIONS_WHITELIST": "jira_all,confluence_all,tempo_all",
+    "JICON_PERMISSIONS_BLACKLIST": "confluence_delete_page,tempo_delete_worklog"
   }
 }
 ```
@@ -176,10 +182,10 @@ Control what operations are allowed. **By default, Jicon runs in read-only mode*
 **Safe Write** - recommended for controlled write access:
 ```json
 {
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_read", "confluence_write", "tempo_read"],
-    "confluenceWriteHome": true
+  "env": {
+    "JICON_PERMISSIONS_MODE": "custom",
+    "JICON_PERMISSIONS_WHITELIST": "jira_read,confluence_write,tempo_read",
+    "JICON_CONFLUENCE_WRITE_HOME": "true"
   }
 }
 ```
@@ -189,34 +195,34 @@ This configuration allows:
 - **Confluence**: Write restricted to your personal space only
 - **Tempo**: Read-only (view worklogs, no time logging)
 
-The `confluenceWriteHome: true` setting ensures all Confluence write operations (drafts, comments, attachments) can only target your personal space, preventing accidental modifications to shared team spaces.
-
 **Draft Only** - create new documents without reading existing content:
 ```json
 {
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["confluence_draft"]
+  "env": {
+    "JICON_PERMISSIONS_MODE": "custom",
+    "JICON_PERMISSIONS_WHITELIST": "confluence_draft"
   }
 }
 ```
 
-Includes: `confluence_draft_create`, `confluence_draft_save`, `confluence_draft_delete`, plus space discovery (`confluence_get_current_user_space`, `confluence_list_spaces`) to know where to create drafts. No page content is exposed.
-
 **Virtual actions** (for whitelist): `jira_read`, `jira_write`, `jira_all`, `confluence_read`, `confluence_write`, `confluence_draft`, `confluence_all`, `tempo_read`, `tempo_write`, `tempo_all`
 
-**Individual tools** (for blacklist): See [TOOL_LIST.md](TOOL_LIST.md) for all tool names (e.g., `confluence_delete_page`, `tempo_delete_worklog`)
+**Individual tools** (for blacklist): See [TOOL_LIST.md](TOOL_LIST.md) for all tool names
 
-### Docker Configuration
+### PlantUML Configuration
 
-PlantUML validation requires Docker. The container starts when MCP loads and does **not auto-restart** if it stops - you'll need to restart the MCP server.
+PlantUML validation requires an external PlantUML server. If not configured, PlantUML tools are disabled.
 
-**Disable Docker/PlantUML** - if you don't need PlantUML validation:
+**Configure PlantUML server**:
 ```json
-{ "disableDocker": true }
+{
+  "env": {
+    "JICON_PLANTUML_SERVER_URL": "http://localhost:8080"
+  }
+}
 ```
 
-When disabled, PlantUML tools return clear errors instead of failing silently.
+You can use the public PlantUML server (`http://www.plantuml.com/plantuml`) or run your own with Docker: `docker run -d -p 8080:8080 plantuml/plantuml-server:jetty`.
 
 ### PlantUML Include Expansion
 
@@ -253,7 +259,7 @@ C4-PlantUML, AWS icons, and Azure diagrams require `!include` directives. By def
 - **Jira** Server/Data Center or Cloud with API access
 - **Confluence** (optional) Server/Data Center or Cloud
 - **Tempo** (optional) Timesheets plugin
-- **Docker** (optional) For PlantUML diagram validation
+- **PlantUML Server** (optional) External server for diagram validation
 
 ## API Limitations
 
@@ -274,7 +280,7 @@ The Confluence Data Center REST API has specific limitations for draft managemen
 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
+3. User approves to publish changes to the original page
 
 This achieves "draft before publish" semantics within API constraints.
 
@@ -286,38 +292,38 @@ This achieves "draft before publish" semantics within API constraints.
 
 ## Features
 
-### 69 Tools Across 3 Services
+### 75 Tools Across 3 Services
 
 | Service | Capabilities |
 |---------|--------------|
-| **Jira** (18 tools) | Search, create, update, transition issues; manage comments, links, watchers; access boards, sprints, worklogs |
+| **Jira** (22 tools) | Search, create, update, transition issues; manage comments, links, watchers; access boards, sprints, worklogs; **LLM-powered analysis** |
 | **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.
+Plus utility tools for content buffering, time calculations, URL generation, date resolution, and built-in help.
 
-### Buffered Responses
+### LLM-Powered Analysis Tools
 
-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:
+These **intelligent entry points** are designed for AI synthesis - they return pre-processed content directly to the LLM (not buffered) for analysis and insight generation:
 
-```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"
-}
-```
+| Tool | Purpose |
+|------|---------|
+| **Activity Digest** | Fetches comments, status/priority/assignee changes across issues. Ask: *"What happened on project X this week?"* |
+| **Recent Comments** | Aggregates comments across multiple issues. Ask: *"Any blockers mentioned in recent discussions?"* |
+| **Changelog** | Tracks field changes across issues. Ask: *"What issues had priority escalations?"* |
+| **Analyze Epic** | Comprehensive Epic analysis: hierarchy breakdown, time metrics, velocity, linked Confluence pages, recent discussions. Ask: *"Analyze Epic PROJ-100 for progress and risks"* |
 
-**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
+These tools return **markdown formatted for LLM comprehension** with pre-computed summaries (counts, breakdowns), enabling the AI to focus on **insight and synthesis** rather than data extraction.
 
-The buffer metadata includes `resourceType` and `title` to track origin (e.g., which query or resource the data came from).
+### 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:
+
+**Buffer capabilities:**
+- Read content in chunks or search within buffered data
+- Server-side data transformation: filtering, grouping, sorting, aggregations
+- Export to multiple formats: XHTML tables, lists, CSV, JSON, Markdown
+- Track buffer origin with metadata (resource type, query, title)
 
 ### Safe Confluence Editing (Review Workflow)
 
@@ -332,21 +338,13 @@ Confluence write operations use a **review workflow** for safety:
 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
+4. **Publish or Discard**: Apply changes to the original page, discard them, or manually copy 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.
 
-**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
 
-Create and validate UML diagrams directly in Confluence pages. The PlantUML Docker container starts automatically when the MCP server loads (if Docker is available). If Docker is unavailable or the container stops, PlantUML tools return clear errors - restart the MCP server to retry. Use `"disableDocker": true` in config to skip PlantUML entirely.
+Create and validate UML diagrams directly in Confluence pages. Configure `JICON_PLANTUML_SERVER_URL` to enable diagram validation. If not configured, PlantUML tools return clear errors explaining how to enable them.
 
 ## Tool Reference
 
@@ -358,7 +356,7 @@ For complete tool documentation with parameters and examples, see **[TOOL_LIST.m
 - Use API tokens with minimal required permissions
 - Rotate tokens regularly
 - Use read-only mode for exploration
-- Never commit `.jicon.json` to version control
+- Never commit credentials to version control
 
 ## License