@crypto512/jicon-mcp 0.7.0 → 1.0.0

package/CLAUDE.md

@@ -1,947 +0,0 @@
-# Jira, Confluence, and Tempo MCP Server
-
-## Overview
-
-A Model Context Protocol (MCP) server that provides seamless integration with Atlassian Jira, Confluence, and Tempo Server/Data Center instances. This server enables AI assistants to interact with Jira issues, projects, boards, Confluence pages, spaces, content, and Tempo time tracking through a comprehensive set of tools.
-
-## Features
-
-### Jira Integration
-- **Issue Management**: Search, create, update, and transition issues
-- **Project Operations**: List projects, components, and versions
-- **Agile Support**: Access boards, sprints, and backlogs
-- **Comments & Collaboration**: Add and retrieve comments on issues
-- **Issue Linking**: Create and manage relationships between issues
-- **Advanced Search**: Execute JQL queries for complex issue searches
-- **Recursive Worklogs**: Sum worklogs for an issue and all its children (sub-tasks, Epic children)
-
-### Confluence Integration
-- **Content Management**: Create, read, update Confluence pages
-- **Search Capabilities**: Execute CQL queries to find content
-- **Space Operations**: List and manage Confluence spaces
-- **Page Hierarchy**: Navigate parent-child page relationships
-- **Attachments**: Upload and retrieve file attachments
-- **Comments**: Add and view page comments
-
-### Tempo Integration
-- **Time Tracking**: Log, view, and manage work time
-- **Worklog Management**: Create, update, and delete worklogs
-- **Team Tracking**: Access team worklogs and time tracking data
-- **Epic Worklogs**: Get all worklogs for an Epic and its children in one call
-- **Account Management**: View and manage Tempo accounts
-- **User Info**: Retrieve user time tracking information
-- **v4 API**: Uses Tempo v4 API with automatic key-to-ID conversion
-
-## Installation
-
-```bash
-# Install globally
-npm install -g @crypto512/jicon-mcp
-
-# Or run directly with npx
-npx @crypto512/jicon-mcp
-```
-
-## Configuration
-
-The server supports multiple authentication methods depending on your Atlassian instance type.
-
-### Jira/Confluence Cloud (Basic Auth)
-
-For Cloud instances, use email + API token with Basic authentication:
-
-```bash
-# Jira Configuration
-JIRA_URL=https://your-domain.atlassian.net
-JIRA_USERNAME=your-email@example.com
-JIRA_API_TOKEN=your-jira-api-token
-
-# Confluence Configuration
-CONFLUENCE_URL=https://your-domain.atlassian.net/wiki
-CONFLUENCE_USERNAME=your-email@example.com
-CONFLUENCE_API_TOKEN=your-confluence-api-token
-```
-
-### Jira/Confluence Data Center 8.14+ (Bearer Auth with PAT)
-
-For Data Center instances version 8.14 and later (including 9.x), use Personal Access Tokens (PAT) with Bearer authentication. Simply omit the `USERNAME` variable or set `AUTH_TYPE=bearer`:
-
-```bash
-# Jira Configuration (PAT - recommended for Data Center)
-JIRA_URL=https://jira.example.com
-JIRA_API_TOKEN=your-personal-access-token
-JIRA_AUTH_TYPE=bearer
-
-# Confluence Configuration (PAT - recommended for Data Center)
-CONFLUENCE_URL=https://confluence.example.com
-CONFLUENCE_API_TOKEN=your-personal-access-token
-CONFLUENCE_AUTH_TYPE=bearer
-```
-
-**Note**: To generate a Personal Access Token in Jira/Confluence Data Center:
-1. Click your avatar → Profile
-2. Select "Personal access tokens" in the left menu
-3. Create a new token with appropriate permissions
-
-### Tempo Configuration
-
-Tempo uses the same authentication as Jira (same URL and credentials). This server uses **Tempo v4 API**, which requires issueId and projectId (integers) instead of string keys. The server automatically converts user-friendly keys (e.g., "PROJ-123") to the numeric IDs required by the v4 API.
-
-**Requirements:**
-- Tempo 3.x or later (which provides v4 API)
-- Same Jira credentials for authentication
-
-### Claude Desktop Configuration
-
-#### For Jira/Confluence Cloud:
-
-**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "jicon": {
-      "command": "npx",
-      "args": ["-y", "@crypto512/jicon-mcp"],
-      "env": {
-        "JIRA_URL": "https://your-domain.atlassian.net",
-        "JIRA_USERNAME": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-jira-api-token",
-        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
-        "CONFLUENCE_USERNAME": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-confluence-api-token"
-      }
-    }
-  }
-}
-```
-
-#### For Jira/Confluence Data Center 8.14+ with PAT:
-
-```json
-{
-  "mcpServers": {
-    "jicon": {
-      "command": "npx",
-      "args": ["-y", "@crypto512/jicon-mcp"],
-      "env": {
-        "JIRA_URL": "https://jira.example.com",
-        "JIRA_API_TOKEN": "your-personal-access-token",
-        "JIRA_AUTH_TYPE": "bearer",
-        "CONFLUENCE_URL": "https://confluence.example.com",
-        "CONFLUENCE_API_TOKEN": "your-personal-access-token",
-        "CONFLUENCE_AUTH_TYPE": "bearer"
-      }
-    }
-  }
-}
-```
-
-## Tools
-
-### Jira Tools
-
-#### `jira_jql_help`
-Get JQL (Jira Query Language) syntax guide and examples on-demand.
-
-Returns a comprehensive JQL reference including operators, common examples, and tips. Use this when you need help constructing JQL queries.
-
-**Parameters:** None
-
-#### `jira_search_issues`
-Search for Jira issues using JQL (Jira Query Language).
-
-Automatically fetches ALL matching results (up to 5000) with buffering. Large responses are automatically buffered - use buffer_get_chunk or buffer_grep to access.
-
-**Parameters:**
-- `jql` (string, required): JQL query string
-- `fields` (string[], optional): Specific fields to return
-
-**Example:**
-```typescript
-{
-  "jql": "project = PROJ AND status = 'In Progress'",
-  "fields": ["summary", "status", "assignee"]
-}
-```
-
-#### `jira_get_issue`
-Get detailed information about a specific Jira issue.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key (e.g., "PROJ-123")
-- `fields` (string[], optional): Specific fields to return
-- `expand` (string[], optional): Additional data to expand (e.g., "changelog", "renderedFields")
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123",
-  "expand": ["changelog"]
-}
-```
-
-#### `jira_create_issue`
-Create a new Jira issue.
-
-**Parameters:**
-- `projectKey` (string, required): Project key
-- `issueType` (string, required): Issue type (e.g., "Bug", "Story", "Task")
-- `summary` (string, required): Issue summary
-- `description` (string, optional): Issue description
-- `priority` (string, optional): Priority name
-- `assignee` (string, optional): Assignee username
-- `labels` (string[], optional): Array of labels
-- `components` (string[], optional): Array of component names
-- `customFields` (object, optional): Custom field values
-
-**Example:**
-```typescript
-{
-  "projectKey": "PROJ",
-  "issueType": "Bug",
-  "summary": "Login button not responding",
-  "description": "When clicking the login button, nothing happens",
-  "priority": "High",
-  "labels": ["ui", "authentication"]
-}
-```
-
-#### `jira_update_issue`
-Update an existing Jira issue.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-- `fields` (object, required): Fields to update
-- `notifyUsers` (boolean, optional): Send notifications (default: true)
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123",
-  "fields": {
-    "summary": "Updated summary",
-    "priority": { "name": "Critical" }
-  }
-}
-```
-
-#### `jira_transition_issue`
-Transition an issue to a different status.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-- `transitionName` (string, required): Transition name (e.g., "In Progress", "Done")
-- `comment` (string, optional): Comment to add with transition
-- `fields` (object, optional): Fields to update during transition
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123",
-  "transitionName": "Done",
-  "comment": "Completed and tested"
-}
-```
-
-#### `jira_add_comment`
-Add a comment to a Jira issue.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-- `comment` (string, required): Comment text (supports Jira markdown)
-- `visibility` (object, optional): Visibility restrictions
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123",
-  "comment": "This has been fixed in the latest build"
-}
-```
-
-#### `jira_get_issue_comments`
-Retrieve all comments from a Jira issue.
-
-Returns all comments for the issue. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-- `orderBy` (string, optional): Sort order ("created" or "-created")
-
-#### `jira_get_issue_worklogs`
-Retrieve all worklogs from a Jira issue.
-
-Use this tool to analyze time logged against a specific issue. Returns worklog entries with author, date, time spent, and a total time summary.
-
-Example: Get worklogs for PROJ-123 to see how much time was logged.
-
-Large responses are automatically buffered - use buffer_get_chunk or buffer_grep to access.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key (e.g., "PROJ-123")
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123"
-}
-```
-
-#### `jira_get_total_worklogs`
-Get total worklogs for an issue and all its children recursively.
-
-Calculates the sum of all time logged on:
-- The specified issue
-- All sub-tasks
-- All issues in the Epic (if the issue is an Epic)
-
-Returns a breakdown by issue and a grand total. Automatically detects the Epic Link field in your Jira instance.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key (e.g., "PROJ-123")
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-100"
-}
-```
-
-**Response:**
-```json
-{
-  "rootIssue": "PROJ-100",
-  "totalTimeSpentSeconds": 86400,
-  "totalTimeSpent": "24h",
-  "totalWorklogCount": 15,
-  "issueCount": 5,
-  "breakdown": [
-    {
-      "issueKey": "PROJ-100",
-      "summary": "Epic: Implement feature X",
-      "issueType": "Epic",
-      "timeSpentSeconds": 3600,
-      "timeSpent": "1h",
-      "worklogCount": 2
-    }
-  ]
-}
-```
-
-#### `jira_list_projects`
-List all accessible Jira projects.
-
-**Parameters:**
-- `recent` (boolean, optional): Only return recent projects
-- `expand` (string[], optional): Additional data to expand
-
-#### `jira_get_project`
-Get detailed information about a specific project.
-
-**Parameters:**
-- `projectKey` (string, required): Project key
-- `expand` (string[], optional): Additional data to expand
-
-#### `jira_get_transitions`
-Get available transitions for an issue.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-
-#### `jira_link_issues`
-Create a link between two issues.
-
-**Parameters:**
-- `issueKey` (string, required): Source issue key
-- `linkedIssueKey` (string, required): Target issue key
-- `linkType` (string, required): Link type (e.g., "Blocks", "Relates to")
-- `comment` (string, optional): Comment for the link
-
-**Example:**
-```typescript
-{
-  "issueKey": "PROJ-123",
-  "linkedIssueKey": "PROJ-456",
-  "linkType": "Blocks"
-}
-```
-
-#### `jira_get_board`
-Get information about an Agile board.
-
-**Parameters:**
-- `boardId` (number, required): Board ID
-
-#### `jira_get_sprints`
-List all sprints for a board.
-
-Returns all sprints for the board. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `boardId` (number, required): Board ID
-- `state` (string, optional): Sprint state filter ("active", "future", "closed")
-
-#### `jira_get_sprint_issues`
-Get all issues in a specific sprint.
-
-Returns all issues for the sprint. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `sprintId` (number, required): Sprint ID
-
-### Confluence Tools
-
-#### `confluence_cql_help`
-Get CQL (Confluence Query Language) syntax guide and examples on-demand.
-
-Returns a comprehensive CQL reference including operators, common examples, critical warnings about invalid syntax (like not using `content~` or `body~`), and tips. Use this when you need help constructing CQL queries.
-
-**Parameters:** None
-
-#### `confluence_search_content`
-Search Confluence content using CQL (Confluence Query Language).
-
-**Parameters:**
-- `cql` (string, required): CQL query string
-- `limit` (number, optional): Maximum results per page (default: 25). When fetchAll=true, max total results (default: 5000)
-- `expand` (string[], optional): Additional data to expand
-- `start` (number, optional): Index of first result (0-based). Ignored when fetchAll=true
-- `fetchAll` (boolean, optional): Automatically fetch all results across pages (default: false, max: 5000)
-
-**Example:**
-```typescript
-{
-  "cql": "type=page AND space=DOCS AND title~'API'",
-  "fetchAll": true,
-  "limit": 100
-}
-```
-
-#### `confluence_get_page`
-Get a Confluence page by ID.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `expand` (string[], optional): Additional data to expand (e.g., "body.storage", "version")
-
-**Example:**
-```typescript
-{
-  "pageId": "123456",
-  "expand": ["body.storage", "version", "ancestors"]
-}
-```
-
-#### `confluence_get_page_by_title`
-Get a Confluence page by title and space.
-
-**Parameters:**
-- `spaceKey` (string, required): Space key
-- `title` (string, required): Page title
-- `expand` (string[], optional): Additional data to expand
-
-**Example:**
-```typescript
-{
-  "spaceKey": "DOCS",
-  "title": "API Documentation"
-}
-```
-
-#### `confluence_create_page`
-Create a new Confluence page.
-
-**Parameters:**
-- `spaceKey` (string, required): Space key
-- `title` (string, required): Page title
-- `content` (string, required): Page content (Confluence storage format or HTML)
-- `parentId` (string, optional): Parent page ID
-- `labels` (string[], optional): Array of labels
-
-**Example:**
-```typescript
-{
-  "spaceKey": "DOCS",
-  "title": "New Feature Documentation",
-  "content": "<p>This page describes the new feature...</p>",
-  "labels": ["api", "v2"]
-}
-```
-
-#### `confluence_update_page`
-Update an existing Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `title` (string, optional): New title
-- `content` (string, optional): New content
-- `version` (number, required): Current version number (for optimistic locking)
-- `minorEdit` (boolean, optional): Whether this is a minor edit
-
-**Example:**
-```typescript
-{
-  "pageId": "123456",
-  "content": "<p>Updated content...</p>",
-  "version": 5
-}
-```
-
-#### `confluence_delete_page`
-Delete a Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-
-#### `confluence_list_spaces`
-List all accessible Confluence spaces.
-
-Returns all spaces accessible to the current user. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `type` (string, optional): Space type filter ("global" or "personal")
-
-#### `confluence_get_space`
-Get detailed information about a space.
-
-**Parameters:**
-- `spaceKey` (string, required): Space key
-- `expand` (string[], optional): Additional data to expand
-
-#### `confluence_get_page_children`
-Get all child pages of a page.
-
-Returns all child pages for the given parent page. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `pageId` (string, required): Parent page ID
-- `expand` (string[], optional): Additional data to expand
-
-#### `confluence_add_comment`
-Add a comment to a Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `comment` (string, required): Comment text (HTML format)
-
-#### `confluence_get_comments`
-Get all comments on a Confluence page.
-
-Returns all comments for the given page. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-
-#### `confluence_upload_attachment`
-Upload an attachment to a Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `filePath` (string, required): Local file path
-- `comment` (string, optional): Attachment comment
-
-#### `confluence_list_attachments`
-List all attachments on a Confluence page.
-
-Returns all attachments for the given page. If the response is large, it will be automatically buffered.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-
-### Utility Tools
-
-#### `workload_convert`
-Convert workload time between different units (seconds, hours, days).
-
-Pure computation tool that helps with time tracking calculations. Automatically included as a dependency when using any Jira, Confluence, or Tempo tool.
-
-**Parameters:**
-- `value` (number, required): The time value to convert
-- `unit` (string, required): The unit of the input value ("seconds", "hours", or "days")
-- `hoursPerDay` (number, optional): Hours per work day (default: 8)
-
-**Example:**
-```typescript
-{
-  "value": 28800,
-  "unit": "seconds"
-}
-```
-
-**Response:**
-```json
-{
-  "seconds": 28800,
-  "hours": 8,
-  "days": 1,
-  "formatted": "1d"
-}
-```
-
-#### `workload_sum`
-Sum multiple workload values with mixed units.
-
-Pure computation tool for aggregating time from multiple sources. Automatically included as a dependency when using any Jira, Confluence, or Tempo tool.
-
-**Parameters:**
-- `values` (array, required): Array of objects with `value` and `unit` properties
-- `hoursPerDay` (number, optional): Hours per work day (default: 8)
-
-**Example:**
-```typescript
-{
-  "values": [
-    { "value": 3600, "unit": "seconds" },
-    { "value": 2, "unit": "hours" },
-    { "value": 0.5, "unit": "days" }
-  ]
-}
-```
-
-**Response:**
-```json
-{
-  "itemCount": 3,
-  "seconds": 25200,
-  "hours": 7,
-  "days": 0.875,
-  "formatted": "7.0h"
-}
-```
-
-## Authentication
-
-The server supports multiple authentication methods depending on your Atlassian instance:
-
-### Basic Authentication (Jira/Confluence Cloud)
-For Cloud instances, use API tokens with Basic Auth:
-- **Username**: Your email address (e.g., user@example.com)
-- **Token**: API token generated from your Atlassian account settings
-- **Method**: Basic Auth (automatically used when username is provided)
-
-Generate Cloud API tokens at: https://id.atlassian.com/manage-profile/security/api-tokens
-
-### Bearer Token Authentication (Jira/Confluence Data Center 8.14+)
-For Data Center instances version 8.14 and later (including 9.x), use Personal Access Tokens (PAT):
-- **Token**: Personal Access Token generated from your Jira/Confluence profile
-- **Method**: Bearer Auth (automatically used when username is omitted or `authType=bearer` is set)
-- **Recommended for**: Jira 9.x, Confluence 7.9+
-
-To generate a PAT:
-1. Log into your Jira/Confluence Data Center instance
-2. Click your avatar → Profile
-3. Select "Personal access tokens" from the left menu
-4. Click "Create token" and set appropriate permissions
-5. Copy the token immediately (it won't be shown again)
-
-### Authentication Auto-Detection
-The server automatically detects the authentication method:
-- If `username` is provided → uses **Basic Auth**
-- If `username` is omitted → uses **Bearer Auth**
-- If `authType` is explicitly set → uses the specified method
-
-## Error Handling
-
-All tools return structured error responses:
-
-```typescript
-{
-  "error": true,
-  "message": "Description of the error",
-  "statusCode": 401,
-  "details": { /* Additional error context */ }
-}
-```
-
-Common error scenarios:
-- **401 Unauthorized**: Invalid credentials or token
-- **403 Forbidden**: Insufficient permissions
-- **404 Not Found**: Resource doesn't exist
-- **400 Bad Request**: Invalid parameters
-- **500 Internal Server Error**: Server-side issue
-
-## Best Practices
-
-### Security
-- **Never commit credentials to version control** - Use .gitignore to exclude .jicon.json and .env files
-- **Use environment variables or secure credential storage** - Leverage hierarchical config (project > user > env)
-- **Start with read-only mode** - Use `"mode": "readonly"` for exploration and reporting tasks
-- **API tokens should have minimal required permissions** - Create tokens with only the necessary scopes
-- **Regularly rotate API tokens** - Set expiration dates and rotate every 90 days
-- **Use Personal Access Tokens (PAT) for Data Center** - More secure than username/password for DC 8.14+
-- **Monitor write operations** - Enable audit logging in your Atlassian instances
-- **Review permission configurations** - Regularly audit your .jicon.json whitelist/blacklist settings
-
-### Automatic Response Buffering
-
-All tools return complete data automatically. When a response exceeds the size limit (default: 16000 characters), it is automatically buffered:
-
-- **Automatic buffering** - Large responses are stored in a buffer and return a `bufferId`
-- **Use `buffer_get_chunk`** - Retrieve content in chunks using the provided `bufferId`
-- **Use `buffer_grep`** - Search within buffered content using regex patterns (large results are also buffered)
-- **Configure limit** - Set `JICON_MAX_OUTPUT` environment variable to adjust the size limit
-- **Use a sub-agent for analysis** - For complex analysis of large buffered data, spawn a sub-agent (Task tool) to process the buffer efficiently without consuming main conversation context
-
-**Example buffered response:**
-```json
-{
-  "_pagination": true,
-  "status": "SUCCESS - Data retrieved and buffered",
-  "bufferId": "buf_abc123",
-  "totalSize": 45000,
-  "hasMore": true,
-  "next_action": {
-    "tool": "buffer_get_chunk",
-    "args": { "bufferId": "buf_abc123", "offset": 0, "limit": 5000 }
-  }
-}
-```
-
-**Recommended approach for large data:**
-1. Use `buffer_grep` to search for specific patterns
-2. For complex analysis, spawn a sub-agent with the `bufferId` to process data without bloating main context
-
-### Performance Considerations
-- **Filter queries narrowly** - Specific JQL/CQL queries are faster than broad searches
-- **Request only needed fields** - Use the `fields` parameter to reduce response size
-- **Respect API rate limits** - Atlassian Cloud has rate limits; space out bulk operations
-- **Use narrow date ranges for Tempo** - Tempo Server/DC doesn't support pagination, so use focused date filters
-- **Use `buffer_grep` for large responses** - Search within buffered content instead of retrieving everything
-
-## Development
-
-### Project Structure
-```
-jicon/
-├── src/
-│   ├── index.ts              # MCP server entry point
-│   ├── types.ts              # Shared type definitions
-│   │
-│   ├── config/               # Configuration system
-│   │   ├── loader.ts         # Config hierarchy loader
-│   │   ├── types.ts          # Config schemas with Zod
-│   │   └── constants.ts      # Config constants
-│   │
-│   ├── permissions/          # Security & access control
-│   │   ├── tool-registry.ts  # Tool categorization
-│   │   └── filter.ts         # Permission filtering
-│   │
-│   ├── utils/                # Shared utilities
-│   │   ├── http-client.ts    # HTTP/Auth wrapper
-│   │   ├── response-formatter.ts # MCP response formatting
-│   │   ├── content-buffer.ts # Content buffering for large responses
-│   │   ├── buffer-tools.ts   # Buffer management tools
-│   │   └── workload-tools.ts # Time calculation utilities
-│   │
-│   ├── jira/                 # Jira integration (19 tools)
-│   │   ├── client.ts         # Jira API client
-│   │   ├── tools.ts          # Tool definitions
-│   │   ├── formatters.ts     # Response formatting
-│   │   ├── types.ts          # TypeScript types
-│   │   └── defaults.ts       # Default field configs
-│   │
-│   ├── confluence/           # Confluence integration (14 tools)
-│   │   ├── client.ts         # Confluence API client
-│   │   ├── tools.ts          # Tool definitions
-│   │   ├── formatters.ts     # Response formatting
-│   │   ├── types.ts          # TypeScript types
-│   │   └── defaults.ts       # Default field configs
-│   │
-│   └── tempo/                # Tempo integration (12 tools)
-│       ├── client.ts         # Tempo API client
-│       ├── tools.ts          # Tool definitions
-│       ├── formatters.ts     # Response formatting
-│       └── types.ts          # TypeScript types
-│
-├── tests/                    # Test suite (146 tests)
-│   ├── permissions/          # Permission system tests
-│   ├── jira/                 # Jira client tests
-│   ├── confluence/           # Confluence client tests
-│   └── utils/                # Utility tests
-│
-├── .jicon.json.example       # Example full-access config
-├── .jicon.json.readonly      # Example read-only config
-├── .jicon.json.custom        # Example custom permissions
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-### Building
-```bash
-npm install
-npm run build
-```
-
-### Testing
-
-Tests are written in TypeScript and use Node.js built-in test runner with tsx:
-
-```bash
-# Run all tests with tsx
-npx tsx --test tests/**/*.test.ts
-
-# Run specific test file
-npx tsx --test tests/utils/content-buffer.test.ts
-
-# Legacy command (requires compiled dist/)
-npm test
-npm run test:integration
-```
-
-**Note:** Tests import from `dist/`, so run `npm run build` first if testing against compiled output.
-
-## Roadmap
-
-### v1.0 (Current)
-- ✅ Core Jira issue operations
-- ✅ Core Confluence page operations
-- ✅ Basic search capabilities
-- ✅ Authentication support
-
-### v1.1 (Planned)
-- Advanced filtering and sorting
-- Bulk operations
-- Webhooks support
-- Custom field templates
-
-### v1.2 (Future)
-- Jira Automation integration
-- Confluence templates
-- Analytics and reporting
-- Multi-instance support
-
-## Contributing
-
-Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
-
-## License
-
-MIT License - see LICENSE file for details
-
-## Security Best Practices
-
-### Deployment Security
-
-#### 1. Credential Management
-- **Use hierarchical configuration**: Project config (.jicon.json) > User config (~/.config/jicon/jicon.json) > Environment variables
-- **Never commit credentials**: Ensure .jicon.json is in .gitignore
-- **Use PAT for Data Center**: Personal Access Tokens are more secure than username/password for DC 8.14+
-- **Rotate tokens regularly**: Set 90-day expiration and rotate before expiry
-
-#### 2. Permission Configuration
-
-**Permission Modes:**
-- `readonly`: All read tools (Jira read + Confluence read + Tempo read)
-- `full`: All tools including write operations
-- `custom`: Whitelist/blacklist specific virtual actions
-
-**Default Configuration:** `custom` mode with `jira_read` + `confluence_read` (Tempo disabled by default)
-
-**Auto-included Dependencies:** (not configurable separately)
-- Buffer read tools (buffer_get_chunk, buffer_grep, etc.) → included with read actions
-- Buffer write tools (buffer_edit) → included with write actions
-- Workload tools (workload_convert, workload_sum) → included with any Jira/Confluence/Tempo tool
-
-**Virtual Actions (9 total):**
-| Action | Description |
-|--------|-------------|
-| `jira_read` | 14 Jira read tools (includes jira_jql_help) |
-| `jira_write` | 5 Jira write tools |
-| `jira_all` | All 19 Jira tools |
-| `confluence_read` | 9 Confluence read tools (includes confluence_cql_help) |
-| `confluence_write` | 5 Confluence write tools |
-| `confluence_all` | All 14 Confluence tools |
-| `tempo_read` | 9 Tempo read tools |
-| `tempo_write` | 3 Tempo write tools |
-| `tempo_all` | All 12 Tempo tools |
-
-- **Example default configuration** (Jira + Confluence read only):
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_read", "confluence_read"]
-  }
-}
-```
-- **Example read-only configuration** (all read tools including Tempo):
-```json
-{
-  "permissions": {
-    "mode": "readonly"
-  }
-}
-```
-- **Example custom configuration with Tempo**:
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_read", "confluence_read", "tempo_read"]
-  }
-}
-```
-
-#### 3. Network Security
-- **Use HTTPS only**: Atlassian Cloud enforces HTTPS; ensure Data Center uses HTTPS
-- **Network isolation**: Run MCP server in isolated network segments when possible
-- **Firewall rules**: Restrict outbound connections to Atlassian instance IPs only
-
-#### 4. Monitoring & Auditing
-- **Enable Atlassian audit logs**: Monitor API usage in your Atlassian instances
-- **Review permission denials**: Check logs for unauthorized access attempts
-- **Monitor write operations**: Track issue creation, updates, and deletions
-- **Set up alerts**: Configure notifications for suspicious API activity
-
-#### 5. Input Validation
-- **Be cautious with JQL/CQL queries**: Complex queries can impact performance
-- **Validate user inputs**: When building tools that generate JQL/CQL, validate inputs
-- **Use parameterized searches**: Prefer specific field filters over broad text searches
-
-#### 6. Token Permissions
-- **Principle of least privilege**: Grant tokens only necessary permissions
-- **Jira Cloud token permissions**:
-  - Read: View issues, projects, boards
-  - Write: Create/update issues (only if needed)
-  - Admin: Avoid granting admin permissions
-- **Data Center PAT scopes**:
-  - Read: READ scope only for read-only operations
-  - Write: WRITE scope only when modifications needed
-
-### Threat Model
-
-#### Protected Against
-- ✅ **Unauthorized write operations**: Permission system blocks write tools in readonly mode
-- ✅ **Credential exposure**: .gitignore prevents credential commits
-- ✅ **Man-in-the-middle**: HTTPS encryption for all API calls
-- ✅ **Authentication bypass**: Double-check permission enforcement
-
-#### Security Considerations
-- ⚠️ **JQL/CQL injection**: While APIs handle parsing, avoid user-generated queries when possible
-- ⚠️ **Rate limiting**: No built-in rate limiting; respect Atlassian API limits manually
-- ⚠️ **Data exfiltration**: Read-only mode can still read all accessible data
-- ⚠️ **Privilege escalation**: Ensure API tokens don't have excessive permissions
-
-### Incident Response
-
-If credentials are compromised:
-1. **Immediately revoke** the API token in Atlassian settings
-2. **Review audit logs** for unauthorized activity
-3. **Generate new tokens** with appropriate permissions
-4. **Update configurations** with new tokens
-5. **Investigate** how credentials were exposed
-6. **Implement preventive measures** to avoid future exposure
-
-## Support
-
-- GitHub Issues: https://github.com/crypto512/jicon/issues
-- Documentation: https://github.com/crypto512/jicon
-- Community: https://github.com/crypto512/jicon/discussions
-
-## Acknowledgments
-
-Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
-- Use buffer management if tool response is too large.