@crypto512/jicon-mcp 0.6.1 → 0.7.0

package/CLAUDE.md

@@ -13,6 +13,7 @@ A Model Context Protocol (MCP) server that provides seamless integration with At
 - **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
@@ -26,6 +27,7 @@ A Model Context Protocol (MCP) server that provides seamless integration with At
 - **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
@@ -140,19 +142,26 @@ Tempo uses the same authentication as Jira (same URL and credentials). This serv
 
 ### 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
-- `maxResults` (number, optional): Maximum number of results (default: 50)
 - `fields` (string[], optional): Specific fields to return
 
 **Example:**
 ```typescript
 {
   "jql": "project = PROJ AND status = 'In Progress'",
-  "maxResults": 10,
   "fields": ["summary", "status", "assignee"]
 }
 ```
@@ -253,13 +262,74 @@ Add a comment to a Jira issue.
 ```
 
 #### `jira_get_issue_comments`
-Retrieve comments from a Jira issue.
+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
-- `maxResults` (number, optional): Maximum number of comments
 - `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.
 
@@ -305,34 +375,47 @@ Get information about an Agile board.
 - `boardId` (number, required): Board ID
 
 #### `jira_get_sprints`
-List sprints for a board.
+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 issues in a specific sprint.
+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
-- `maxResults` (number, optional): Maximum number of results
 
 ### 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 number of results (default: 25)
+- `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'",
-  "limit": 10
+  "fetchAll": true,
+  "limit": 100
 }
 ```
 
@@ -415,8 +498,9 @@ Delete a Confluence page.
 #### `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:**
-- `limit` (number, optional): Maximum number of results
 - `type` (string, optional): Space type filter ("global" or "personal")
 
 #### `confluence_get_space`
@@ -427,12 +511,13 @@ Get detailed information about a space.
 - `expand` (string[], optional): Additional data to expand
 
 #### `confluence_get_page_children`
-Get child pages of a page.
+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
-- `limit` (number, optional): Maximum number of results
 
 #### `confluence_add_comment`
 Add a comment to a Confluence page.
@@ -442,11 +527,12 @@ Add a comment to a Confluence page.
 - `comment` (string, required): Comment text (HTML format)
 
 #### `confluence_get_comments`
-Get comments on a Confluence page.
+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
-- `limit` (number, optional): Maximum number of results
 
 #### `confluence_upload_attachment`
 Upload an attachment to a Confluence page.
@@ -457,11 +543,73 @@ Upload an attachment to a Confluence page.
 - `comment` (string, optional): Attachment comment
 
 #### `confluence_list_attachments`
-List attachments on a Confluence page.
+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
-- `limit` (number, optional): Maximum number of results
+
+### 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
 
@@ -526,13 +674,41 @@ Common error scenarios:
 - **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
-- **Use pagination for large datasets** - Set appropriate `maxResults` to avoid memory issues
-- **Enable `fetchAll` judiciously** - Auto-pagination can return up to 5000 results, which may be slow
 - **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
 
@@ -554,29 +730,32 @@ jicon/
 │   │
 │   ├── utils/                # Shared utilities
 │   │   ├── http-client.ts    # HTTP/Auth wrapper
-│   │   └── response-formatter.ts # MCP response formatting
+│   │   ├── 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 (15 tools)
+│   ├── 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 (13 tools)
+│   ├── 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 (11 tools)
+│   └── 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 (86 tests)
+├── tests/                    # Test suite (146 tests)
 │   ├── permissions/          # Permission system tests
 │   ├── jira/                 # Jira client tests
 │   ├── confluence/           # Confluence client tests
@@ -597,11 +776,23 @@ 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)
@@ -641,9 +832,42 @@ MIT License - see LICENSE file for details
 - **Rotate tokens regularly**: Set 90-day expiration and rotate before expiry
 
 #### 2. Permission Configuration
-- **Start with read-only mode**: Default to `"mode": "readonly"` for safety
-- **Use custom permissions for specific workflows**: Whitelist only required tools
-- **Example read-only 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": {
@@ -651,7 +875,7 @@ MIT License - see LICENSE file for details
   }
 }
 ```
-- **Example custom configuration**:
+- **Example custom configuration with Tempo**:
 ```json
 {
   "permissions": {
@@ -720,3 +944,4 @@ If credentials are compromised:
 ## Acknowledgments
 
 Built on the [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic.
+- Use buffer management if tool response is too large.