@crypto512/jicon-mcp 0.7.1 → 1.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-> A comprehensive Model Context Protocol (MCP) server for seamless integration with Atlassian Jira and Confluence.
+> Connect Claude to your Jira, Confluence, and Tempo. Search issues, create pages, log time - all through natural conversation.
 
 ## Quick Start
 
@@ -15,188 +15,115 @@ npx @crypto512/jicon-mcp
 npm install -g @crypto512/jicon-mcp
 ```
 
-## What is Jicon?
+## What Can You Do?
 
-Jicon is an MCP server that enables AI assistants like Claude to interact with your Jira, Confluence, and Tempo instances. It provides 52 powerful tools for:
+Once configured, just ask Claude in natural language:
 
-- 🎫 **Jira**: Issue management, searching, project operations, Agile boards, sprints
-- 📄 **Confluence**: Page management, content search, spaces, attachments, comments
-- ⏱️ **Tempo**: Time tracking, worklog management, accounts, and teams
-- 📦 **Buffer**: Content pagination for handling large responses
-
-## Features at a Glance
-
-### Jira (19 Tools)
-- Search issues with JQL
-- Create, update, and transition issues
-- Manage comments, links, and watchers
-- Access boards and sprints
-- View projects, issue types, and metadata
-- Track worklogs (individual and recursive totals)
-
-### Confluence (14 Tools)
-- Search content with CQL
-- Create, update, and delete pages
-- Navigate page hierarchies
-- Manage attachments
-- Add and view comments
-
-### Tempo (12 Tools)
-- Log and manage work time
-- View and update worklogs
-- Access accounts and teams
-- Retrieve team and epic worklogs
-- Get user time tracking info
-
-### Buffer (5 Tools)
-- Retrieve content chunks from buffered responses
-- List active buffers and their metadata
-- Clear buffers to free memory
-- **Search buffered content with grep-like patterns**
-- **Edit buffered content with find/replace**
-
-### Workload (2 Tools)
-- Convert time between units (seconds, hours, days)
-- Sum multiple workload values with mixed units
-
-## Content Buffering
-
-Tools that return large content (Confluence pages, Jira issues, Tempo worklogs) use an in-memory buffering system for efficient content pagination.
+### Jira
+- *"Find all high-priority bugs assigned to me"*
+- *"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"*
+- *"Link PROJ-456 as blocking PROJ-789"*
 
-### How It Works
+### Confluence
+- *"Update the API documentation page with the new endpoints"*
+- *"Create a meeting notes page in the Engineering space"*
+- *"Find all pages about authentication in DOCS"*
+- *"Add a PlantUML diagram to the architecture page"*
 
-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
+### Tempo
+- *"Log 4 hours on PROJ-123 for today with description 'Code review'"*
+- *"Show my worklogs for this week"*
+- *"How much time did the team spend on the Epic last month?"*
 
-### Response Format
+## Setup
 
-Buffered tools return:
-- `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
+### Claude Desktop
 
-### Example Usage
+Add to your `claude_desktop_config.json`:
 
-```typescript
-// 1. Get a Confluence page (returns first 5000 chars)
-{
-  "pageId": "123456"
-}
-// Response: { bufferId: "buf_xxx", content: "...", hasMore: true, totalSize: 15000 }
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
-// 2. Get next chunk
+```json
 {
-  "bufferId": "buf_xxx",
-  "offset": 5000,
-  "limit": 5000
+  "mcpServers": {
+    "jicon": {
+      "command": "npx",
+      "args": ["-y", "@crypto512/jicon-mcp"],
+      "env": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token",
+        "CONFLUENCE_URL": "https://confluence.example.com",
+        "CONFLUENCE_USERNAME": "your-email@example.com",
+        "CONFLUENCE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
 }
-// Response: { content: "...", hasMore: true }
-
-// 3. Continue until hasMore: false
 ```
 
-### Buffered Tools
-
-- `confluence_get_page` - Returns page content with buffering
-- `confluence_get_page_by_title` - Returns page content with buffering
-- `jira_get_issue` - Returns issue data with buffering
-- `tempo_get_worklogs` - Returns worklog data with buffering
-- `tempo_get_team_worklogs` - Returns team worklog data with buffering
-
-### 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
-
-### Searching Buffer Content
-
-Use `buffer_grep` to search within buffered content with regex patterns:
-
-```typescript
-// Search for "meeting" with 2 lines of context before and after
-{
-  "bufferId": "buf_xxx",
-  "pattern": "meeting",
-  "-C": 2
-}
+### Claude Code
 
-// Case-insensitive search with 3 lines after each match
-{
-  "bufferId": "buf_xxx",
-  "pattern": "API",
-  "-i": true,
-  "-A": 3
-}
+Add to `~/.claude/settings.json` or project `.mcp.json`:
 
-// Count occurrences only
+```json
 {
-  "bufferId": "buf_xxx",
-  "pattern": "TODO",
-  "output_mode": "count"
+  "mcpServers": {
+    "jicon": {
+      "command": "npx",
+      "args": ["-y", "@crypto512/jicon-mcp"],
+      "env": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
 }
 ```
 
-**Parameters:**
-- `pattern`: Regex pattern to search for
-- `-A`: Lines to show after each match
-- `-B`: Lines to show before each match
-- `-C`: Lines to show before AND after (overrides -A/-B)
-- `-i`: Case insensitive search
-- `-n`: Show line numbers (default: true)
-- `output_mode`: "content" (default) or "count"
-- `multiline`: Enable multiline mode where `.` matches newlines
-- `head_limit`: Limit to first N matches
-- `offset`: Skip first N matches
-
-### Editing Buffer Content
-
-Use `buffer_edit` to perform find/replace on buffered content:
+### OpenCode
 
-```typescript
-// Replace single occurrence
-{
-  "bufferId": "buf_xxx",
-  "old_string": "Meeting at 2pm",
-  "new_string": "Meeting at 3pm"
-}
+Add to `opencode.jsonc` in your project root or `~/.config/opencode/opencode.jsonc`:
 
-// Replace all occurrences
+```jsonc
 {
-  "bufferId": "buf_xxx",
-  "old_string": "TODO",
-  "new_string": "DONE",
-  "replace_all": true
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "jicon": {
+      "type": "local",
+      "command": ["npx", "-y", "@crypto512/jicon-mcp"],
+      "environment": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
 }
 ```
 
-**Important:** `buffer_edit` modifies content in memory only. To persist changes:
-- For Confluence: call `confluence_update_page` with the modified content
-- For Jira: call `jira_update_issue` with the modified fields
-
-**Workflow Example:**
-1. `confluence_get_page` → get bufferId
-2. `buffer_grep` → find text to replace
-3. `buffer_edit` → replace text in memory
-4. `buffer_get_chunk` → get full modified content
-5. `confluence_update_page` → persist changes
-
 ## Configuration
 
-### Configuration with `.jicon.json`
+### 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 |
+| `CONFLUENCE_URL` | Your Confluence instance URL |
+| `CONFLUENCE_USERNAME` | Your email (omit for Data Center PAT) |
+| `CONFLUENCE_API_TOKEN` | API token or Personal Access Token |
 
-Jicon supports a flexible configuration hierarchy with permission control:
+**Note:** Tempo uses the same Jira credentials - no separate configuration needed.
 
-**Configuration Priority:**
-1. `.jicon.json` (project root) - **Highest priority**
-2. `$HOME/.config/jicon/jicon.json` (user config) - Medium priority
-3. Environment variables - Lowest priority
+### Configuration File (Optional)
 
-**Create `.jicon.json` in your project root:**
+Create `.jicon.json` in your project root for project-specific settings:
 
 ```json
 {
@@ -209,300 +136,106 @@ Jicon supports a flexible configuration hierarchy with permission control:
     "url": "https://confluence.example.com",
     "username": "your-email@example.com",
     "token": "your-api-token"
-  },
-  "permissions": {
-    "mode": "full"
   }
 }
 ```
 
-**Note:** Tempo uses the same Jira URL and credentials - no separate configuration needed.
-
-**⚠️ Important:** Add `.jicon.json` to your `.gitignore` to avoid committing credentials!
+**Important:** Add `.jicon.json` to your `.gitignore`!
 
 ### Permission Modes
 
-Control which tools are allowed to execute:
+Control what operations are allowed:
 
-#### 1. **Full Access** (default)
+**Full Access** (default):
 ```json
 { "permissions": { "mode": "full" } }
 ```
-All 52 tools are available.
 
-#### 2. **Read-Only Mode**
+**Read-Only** - safe for exploration:
 ```json
 { "permissions": { "mode": "readonly" } }
 ```
-Only read operations (36 read tools + auto-included dependencies: 14 Jira + 9 Confluence + 9 Tempo + 4 Buffer read tools, plus workload utilities).
-
-#### 3. **Custom Mode** with Virtual Actions
-
-Simplify configuration with **virtual actions** that group related tools:
-
-**Virtual Actions Available (9 total):**
-- `jira_read` - All 14 Jira read tools
-- `jira_write` - All 5 Jira write tools
-- `jira_all` - All 19 Jira tools
-- `confluence_read` - All 9 Confluence read tools
-- `confluence_write` - All 5 Confluence write tools
-- `confluence_all` - All 14 Confluence tools
-- `tempo_read` - All 9 Tempo read tools
-- `tempo_write` - All 3 Tempo write tools
-- `tempo_all` - All 12 Tempo tools
-
-**Auto-included Dependencies:**
-- Buffer tools (buffer_get_chunk, buffer_grep, etc.) are automatically included with any read/write action
-- Workload tools (workload_convert, workload_sum) are automatically included with any Jira/Confluence/Tempo tool
-
-**Example: Read-only access to all services**
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_read", "confluence_read", "tempo_read"]
-  }
-}
-```
-
-**Example: Full Jira + Confluence read-only + Tempo time tracking**
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_all", "confluence_read", "tempo_all"]
-  }
-}
-```
-
-**Example: Specific tools only**
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": [
-      "jira_search_issues",
-      "jira_get_issue",
-      "jira_create_issue",
-      "confluence_get_page",
-      "tempo_log_work",
-      "tempo_get_worklogs"
-    ]
-  }
-}
-```
 
-**Example: Blacklist dangerous operations**
+**Custom** - fine-grained control:
 ```json
 {
   "permissions": {
     "mode": "custom",
-    "blacklist": ["confluence_delete_page"]
+    "whitelist": ["jira_read", "confluence_read", "tempo_all"]
   }
 }
 ```
 
-See [`.jicon.json.example`](.jicon.json.example), [`.jicon.json.readonly`](.jicon.json.readonly), and [`.jicon.json.custom`](.jicon.json.custom) for more examples.
-
-### Environment Variables
-
-All configuration options can be set via environment variables:
-
-| Variable | Description |
-|----------|-------------|
-| `JIRA_URL` | Jira instance URL |
-| `JIRA_USERNAME` | Username/email (omit for Bearer auth) |
-| `JIRA_API_TOKEN` | API token or PAT |
-| `JIRA_AUTH_TYPE` | `basic` (default) or `bearer` |
-| `CONFLUENCE_URL` | Confluence instance URL |
-| `CONFLUENCE_USERNAME` | Username/email (omit for Bearer auth) |
-| `CONFLUENCE_API_TOKEN` | API token or PAT |
-| `CONFLUENCE_AUTH_TYPE` | `basic` (default) or `bearer` |
+Available virtual actions: `jira_read`, `jira_write`, `jira_all`, `confluence_read`, `confluence_write`, `confluence_all`, `tempo_read`, `tempo_write`, `tempo_all`
 
-### Claude Desktop
+## Authentication
 
-Add to `claude_desktop_config.json`:
+### Atlassian Cloud
 
-```json
-{
-  "mcpServers": {
-    "jicon": {
-      "command": "npx",
-      "args": ["-y", "@crypto512/jicon-mcp"],
-      "env": {
-        "JIRA_URL": "https://jira.example.com",
-        "JIRA_USERNAME": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-api-token",
-        "CONFLUENCE_URL": "https://confluence.example.com",
-        "CONFLUENCE_USERNAME": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
+1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+2. Create a new API token
+3. Use your email as `username` and the token as `token`
 
-Add to `~/.claude/settings.json` or project `.mcp.json`:
+### Jira/Confluence Data Center (8.14+)
 
-```json
-{
-  "mcpServers": {
-    "jicon": {
-      "command": "npx",
-      "args": ["-y", "@crypto512/jicon-mcp"],
-      "env": {
-        "JIRA_URL": "https://jira.example.com",
-        "JIRA_USERNAME": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
+1. Go to your profile → Personal Access Tokens
+2. Create a new token
+3. Use only the `token` field (omit `username`)
+4. Optionally set `"authType": "bearer"`
 
-### OpenCode
+## Requirements
 
-For [OpenCode](https://opencode.ai) 1.0+, add to `opencode.jsonc` in your project root or `~/.config/opencode/opencode.jsonc`:
+- **Node.js 18+**
+- **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
 
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "jicon": {
-      "type": "local",
-      "command": ["npx", "-y", "@crypto512/jicon-mcp"],
-      "environment": {
-        "JIRA_URL": "https://jira.example.com",
-        "JIRA_USERNAME": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-api-token",
-        "CONFLUENCE_URL": "https://confluence.example.com",
-        "CONFLUENCE_USERNAME": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
+## Features
 
-## Example Usage
+### 63 Tools Across 3 Services
 
-Once configured, you can ask Claude to:
+| 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 |
+| **Tempo** (12 tools) | Log time, view/update worklogs, team tracking, accounts |
 
-- *"Find all high-priority bugs assigned to me in the PROJ project"*
-- *"Create a new task for implementing the login feature"*
-- *"Show me the current sprint's progress"*
-- *"Update the API documentation page in Confluence"*
-- *"Search for pages about authentication in the DOCS space"*
-- *"Log 4 hours of work on PROJ-123 for today"*
-- *"Show me my worklogs for this week"*
-- *"Get team worklogs for the development team"*
-
-## Tool Categories
-
-### Jira Tools
-| Category | Tools |
-|----------|-------|
-| **Help** | `jira_jql_help` |
-| **Search & Retrieval** | `jira_search_issues`, `jira_get_issue`, `jira_get_issue_comments` |
-| **Issue Management** | `jira_create_issue`, `jira_update_issue`, `jira_transition_issue` |
-| **Collaboration** | `jira_add_comment`, `jira_link_issues`, `jira_get_issue_watchers` |
-| **Projects** | `jira_list_projects`, `jira_get_project`, `jira_get_issue_types` |
-| **Agile** | `jira_get_board`, `jira_get_sprints`, `jira_get_sprint_issues` |
-| **Workflow** | `jira_get_transitions` |
-| **Time Tracking** | `jira_get_issue_worklogs`, `jira_get_total_worklogs` |
-
-### Confluence Tools
-| Category | Tools |
-|----------|-------|
-| **Help** | `confluence_cql_help` |
-| **Search & Retrieval** | `confluence_search_content`, `confluence_get_page`, `confluence_get_page_by_title` |
-| **Page Management** | `confluence_create_page`, `confluence_update_page`, `confluence_delete_page` |
-| **Spaces** | `confluence_list_spaces`, `confluence_get_space` |
-| **Navigation** | `confluence_get_page_children` |
-| **Collaboration** | `confluence_add_comment`, `confluence_get_comments` |
-| **Attachments** | `confluence_upload_attachment`, `confluence_list_attachments` |
-
-### Tempo Tools
-| Category | Tools |
-|----------|-------|
-| **Worklog Management** | `tempo_get_worklogs`, `tempo_get_worklog`, `tempo_log_work`, `tempo_update_worklog`, `tempo_delete_worklog` |
-| **Team Tracking** | `tempo_get_team_worklogs`, `tempo_get_teams`, `tempo_get_team` |
-| **Epic Tracking** | `tempo_get_epic_worklogs` |
-| **Accounts** | `tempo_get_accounts`, `tempo_get_account` |
-| **User Info** | `tempo_get_user_info` |
-
-### Buffer Tools
-| Category | Tools |
-|----------|-------|
-| **Content Pagination** | `buffer_get_chunk`, `buffer_list`, `buffer_clear` |
-| **Content Search** | `buffer_grep` |
-| **Content Edit** | `buffer_edit` |
-
-### Workload Tools
-| Category | Tools |
-|----------|-------|
-| **Time Conversion** | `workload_convert`, `workload_sum` |
+Plus utility tools for content buffering, time calculations, URL generation, and built-in help.
 
-## Requirements
+### Safe Confluence Editing
 
-- Node.js 18 or higher
-- Jira Server/Data Center or Jira Cloud instance
-- Confluence Server/Data Center or Confluence Cloud instance (optional)
-- Tempo Timesheets instance (optional)
-- Valid API tokens or Personal Access Tokens
+Confluence changes go through a draft workflow - Claude creates drafts, you review and publish. No accidental overwrites.
 
-## Authentication
+### PlantUML Diagrams
 
-### Jira/Confluence Cloud (Basic Auth)
-Generate an API token from your Atlassian account:
-1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
-2. Create a new API token
-3. Use your email as `username` and the token as `token`
+Create and validate UML diagrams directly in Confluence pages. Requires Docker for full syntax validation.
 
-### Jira/Confluence Data Center (Bearer Auth)
-For Data Center 8.14+, use Personal Access Tokens (PAT):
-1. Go to your profile settings
-2. Navigate to "Personal Access Tokens"
-3. Create a new token with required permissions
-4. Omit `username` or set `authType: "bearer"` to use Bearer authentication
+## Tool Reference
 
-**Data Center `.jicon.json` example:**
-```json
-{
-  "jira": {
-    "url": "https://jira.example.com",
-    "token": "your-personal-access-token",
-    "authType": "bearer"
-  }
-}
-```
+For complete tool documentation with parameters and examples, see **[TOOL_LIST.md](TOOL_LIST.md)**.
 
-## Security Best Practices
+## Security
 
-- ✅ Store credentials in environment variables
-- ✅ Use API tokens with minimal required permissions
-- ✅ Regularly rotate API tokens
-- ✅ Never commit credentials to version control
-- ✅ Use read-only tokens for search/read operations
+- Store credentials in environment variables, not in code
+- Use API tokens with minimal required permissions
+- Rotate tokens regularly
+- Use read-only mode for exploration
+- Never commit `.jicon.json` to version control
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ## Support
 
-- 🐛 **Issues**: [GitHub Issues](https://github.com/crypto512/jicon/issues)
-- 💬 **Discussions**: [GitHub Discussions](https://github.com/crypto512/jicon/discussions)
-- 📖 **Documentation**: [GitHub Repository](https://github.com/crypto512/jicon)
+- [GitHub Issues](https://github.com/crypto512/jicon/issues)
+- [GitHub Discussions](https://github.com/crypto512/jicon/discussions)
 
 ## Acknowledgments
 
-- Built on [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
-- Powered by Atlassian APIs
-- Inspired by the community's need for better Jira/Confluence integration
+Built on [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
 
 ---
 
-**Made with ❤️ for developers who work with Jira, Confluence, and Tempo**
+**Made with care for teams using Jira, Confluence, and Tempo**