@crypto512/jicon-mcp 0.6.1 → 0.7.1

package/CLAUDE.md

@@ -1,722 +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
-
-### 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
-- **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_search_issues`
-Search for Jira issues using JQL (Jira Query Language).
-
-**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"]
-}
-```
-
-#### `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 comments from a Jira issue.
-
-**Parameters:**
-- `issueKey` (string, required): Issue key
-- `maxResults` (number, optional): Maximum number of comments
-- `orderBy` (string, optional): Sort order ("created" or "-created")
-
-#### `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 sprints for a board.
-
-**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.
-
-**Parameters:**
-- `sprintId` (number, required): Sprint ID
-- `maxResults` (number, optional): Maximum number of results
-
-### Confluence Tools
-
-#### `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)
-- `expand` (string[], optional): Additional data to expand
-
-**Example:**
-```typescript
-{
-  "cql": "type=page AND space=DOCS AND title~'API'",
-  "limit": 10
-}
-```
-
-#### `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.
-
-**Parameters:**
-- `limit` (number, optional): Maximum number of results
-- `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 child pages of a page.
-
-**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.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `comment` (string, required): Comment text (HTML format)
-
-#### `confluence_get_comments`
-Get comments on a Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `limit` (number, optional): Maximum number of results
-
-#### `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 attachments on a Confluence page.
-
-**Parameters:**
-- `pageId` (string, required): Page ID
-- `limit` (number, optional): Maximum number of results
-
-## 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
-
-### 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
-
-## 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
-│   │
-│   ├── jira/                 # Jira integration (15 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)
-│   │   ├── 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)
-│       ├── client.ts         # Tempo API client
-│       ├── tools.ts          # Tool definitions
-│       ├── formatters.ts     # Response formatting
-│       └── types.ts          # TypeScript types
-│
-├── tests/                    # Test suite (86 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
-```bash
-npm test
-npm run test:integration
-```
-
-## 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
-- **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**:
-```json
-{
-  "permissions": {
-    "mode": "readonly"
-  }
-}
-```
-- **Example custom configuration**:
-```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.