@crypto512/jicon-mcp 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+# Jira Configuration
+JIRA_URL=https://jira.example.com
+JIRA_USERNAME=your-email@example.com
+JIRA_API_TOKEN=your-jira-api-token
+
+# Confluence Configuration
+CONFLUENCE_URL=https://confluence.example.com
+CONFLUENCE_USERNAME=your-email@example.com
+CONFLUENCE_API_TOKEN=your-confluence-api-token

package/.jicon.json.custom

@@ -0,0 +1,21 @@
+{
+  "jira": {
+    "url": "https://jira.example.com",
+    "username": "your-email@example.com",
+    "token": "your-jira-api-token"
+  },
+  "confluence": {
+    "url": "https://confluence.example.com",
+    "username": "your-email@example.com",
+    "token": "your-confluence-api-token"
+  },
+  "permissions": {
+    "mode": "custom",
+    "whitelist": [
+      "jira_read",
+      "jira_create_issue",
+      "confluence_read"
+    ],
+    "blacklist": []
+  }
+}

package/.jicon.json.example

@@ -0,0 +1,15 @@
+{
+  "jira": {
+    "url": "https://jira.example.com",
+    "username": "your-email@example.com",
+    "token": "your-jira-api-token"
+  },
+  "confluence": {
+    "url": "https://confluence.example.com",
+    "username": "your-email@example.com",
+    "token": "your-confluence-api-token"
+  },
+  "permissions": {
+    "mode": "full"
+  }
+}

package/.jicon.json.readonly

@@ -0,0 +1,15 @@
+{
+  "jira": {
+    "url": "https://jira.example.com",
+    "username": "your-email@example.com",
+    "token": "your-jira-api-token"
+  },
+  "confluence": {
+    "url": "https://confluence.example.com",
+    "username": "your-email@example.com",
+    "token": "your-confluence-api-token"
+  },
+  "permissions": {
+    "mode": "readonly"
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,596 @@
+# Jira and Confluence MCP Server
+
+## Overview
+
+A Model Context Protocol (MCP) server that provides seamless integration with Atlassian Jira and Confluence Server/Data Center instances. This server enables AI assistants to interact with Jira issues, projects, boards, and Confluence pages, spaces, and content 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
+
+## 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
+
+### 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
+
+### Rate Limiting
+The server implements intelligent rate limiting to respect Atlassian API limits:
+- Automatic retry with exponential backoff
+- Request queuing to prevent overwhelming the API
+- Configurable rate limits per endpoint
+
+### Caching
+Certain read-only operations are cached to improve performance:
+- Project metadata (5 minutes)
+- User information (10 minutes)
+- Space information (5 minutes)
+
+### Security
+- Never commit credentials to version control
+- Use environment variables or secure credential storage
+- API tokens should have minimal required permissions
+- Regularly rotate API tokens
+
+## Development
+
+### Project Structure
+```
+jicon/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── jira/
+│   │   ├── client.ts         # Jira API client
+│   │   ├── tools.ts          # Jira tool implementations
+│   │   └── types.ts          # Jira type definitions
+│   ├── confluence/
+│   │   ├── client.ts         # Confluence API client
+│   │   ├── tools.ts          # Confluence tool implementations
+│   │   └── types.ts          # Confluence type definitions
+│   └── utils/
+│       ├── auth.ts           # Authentication utilities
+│       ├── cache.ts          # Caching layer
+│       └── rate-limit.ts     # Rate limiting
+├── tests/
+│   ├── jira/
+│   └── confluence/
+├── 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
+
+## 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.