@crypto512/jicon-mcp 1.3.0 → 2.0.0

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)
 
@@ -110,65 +118,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_DISABLE_DOCKER` | `true`\|`false` | `false` | Disable PlantUML/Docker features |
+| `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:
-```json
-{ "permissions": { "mode": "readonly" } }
-```
-
-**Full Access** - all operations enabled:
+**Full Access**:
 ```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 +180,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,31 +193,31 @@ 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 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.
 
-**Disable Docker/PlantUML** - if you don't need PlantUML validation:
+**Disable Docker/PlantUML**:
 ```json
-{ "disableDocker": true }
+{
+  "env": {
+    "JICON_DISABLE_DOCKER": "true"
+  }
+}
 ```
 
 When disabled, PlantUML tools return clear errors instead of failing silently.
@@ -274,7 +278,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,7 +290,7 @@ This achieves "draft before publish" semantics within API constraints.
 
 ## Features
 
-### 69 Tools Across 3 Services
+### 71 Tools Across 3 Services
 
 | Service | Capabilities |
 |---------|--------------|
@@ -300,24 +304,11 @@ Plus utility tools for content buffering, time calculations, URL generation, and
 
 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).
+**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,18 +323,10 @@ 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.
@@ -358,7 +341,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