@crypto512/jicon-mcp 0.7.0 → 1.0.0

package/DEVELOPMENT.md

@@ -1,400 +0,0 @@
-# Development Guide - Testing Jicon MCP Server
-
-## Testing Your Development Version
-
-There are several ways to test the MCP server during development:
-
-## Method 1: Claude Desktop with Local Build (Recommended)
-
-### Step 1: Build the Project
-```bash
-npm run build
-```
-
-### Step 2: Configure Claude Desktop
-
-Edit your Claude Desktop configuration file:
-
-**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "jicon-dev": {
-      "command": "node",
-      "args": ["/absolute/path/to/jicon/dist/index.js"],
-      "env": {
-        "JIRA_URL": "https://jira.example.com",
-        "JIRA_USERNAME": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-test-token",
-        "CONFLUENCE_URL": "https://confluence.example.com",
-        "CONFLUENCE_USERNAME": "your-email@example.com",
-        "CONFLUENCE_API_TOKEN": "your-test-token"
-      }
-    }
-  }
-}
-```
-
-**Or use `.jicon.json` in the project directory:**
-
-```json
-{
-  "mcpServers": {
-    "jicon-dev": {
-      "command": "node",
-      "args": ["/absolute/path/to/jicon/dist/index.js"]
-    }
-  }
-}
-```
-
-Then create `.jicon.json` in your project:
-
-```json
-{
-  "jira": {
-    "url": "https://jira.example.com",
-    "username": "your-email@example.com",
-    "token": "your-test-token"
-  },
-  "confluence": {
-    "url": "https://confluence.example.com",
-    "username": "your-email@example.com",
-    "token": "your-test-token"
-  },
-  "permissions": {
-    "mode": "readonly"
-  }
-}
-```
-
-### Step 3: Restart Claude Desktop
-
-1. Quit Claude Desktop completely
-2. Start Claude Desktop again
-3. The server should appear in the MCP menu (hammer icon)
-
-### Step 4: Test in Claude
-
-Ask Claude to use the tools:
-```
-Can you search for issues in project TEST using Jira?
-```
-
----
-
-## Method 2: MCP Inspector (Best for Debugging)
-
-The MCP Inspector is a tool from Anthropic for testing MCP servers.
-
-### Install MCP Inspector
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
-
-This opens a web interface where you can:
-- See all available tools
-- Test tool execution
-- Inspect requests/responses
-- Debug errors
-
-### With Configuration File
-
-Create `.jicon.json` in the project root first, then:
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
-
-The inspector will read your config automatically.
-
----
-
-## Method 3: Manual Testing with stdio
-
-### Test the Server Directly
-
-```bash
-# Build first
-npm run build
-
-# Run the server
-node dist/index.js
-```
-
-You should see:
-```
-✓ Using environment variables (or config file info)
-✓ Jira configured: https://jira.example.com
-✓ Confluence configured: https://confluence.example.com
-✓ Permission mode: full
-✓ Allowed tools: 28/28
-Jicon MCP Server running on stdio
-```
-
-### Send Test JSON-RPC Request
-
-The server communicates via JSON-RPC over stdio. You can test manually:
-
-```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
-```
-
----
-
-## Method 4: npm link for Global Testing
-
-Make your dev version available globally:
-
-```bash
-# In the jicon directory
-npm link
-
-# Now you can use it anywhere
-jicon-mcp
-```
-
-Then in Claude Desktop config:
-```json
-{
-  "mcpServers": {
-    "jicon-dev": {
-      "command": "jicon-mcp"
-    }
-  }
-}
-```
-
----
-
-## Testing Different Configurations
-
-### Test Read-Only Mode
-
-Create `.jicon.json`:
-```json
-{
-  "jira": { "url": "...", "username": "...", "token": "..." },
-  "confluence": { "url": "...", "username": "...", "token": "..." },
-  "permissions": {
-    "mode": "readonly"
-  }
-}
-```
-
-Ask Claude to try creating an issue - it should be denied:
-```
-Create a Jira issue in project TEST
-```
-
-Expected: Error message about permission denied.
-
-### Test Virtual Actions
-
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_read", "confluence_read"]
-  }
-}
-```
-
-Test that only read actions work.
-
-### Test Whitelist
-
-```json
-{
-  "permissions": {
-    "mode": "custom",
-    "whitelist": ["jira_search_issues", "jira_get_issue"]
-  }
-}
-```
-
-Only those 2 tools should be available.
-
----
-
-## Development Workflow
-
-### 1. Make Changes to Code
-
-Edit files in `src/`:
-```bash
-vim src/jira/tools.ts
-```
-
-### 2. Rebuild
-
-```bash
-npm run build
-```
-
-Or use watch mode:
-```bash
-npm run watch
-```
-
-### 3. Restart Claude Desktop
-
-- Quit Claude Desktop
-- Start it again
-- Test your changes
-
-### 4. Check Logs
-
-**MacOS Logs:**
-```bash
-tail -f ~/Library/Logs/Claude/mcp*.log
-```
-
-**Windows Logs:**
-```
-%APPDATA%\Claude\logs\
-```
-
-Look for errors or debug output from your server.
-
----
-
-## Debugging Tips
-
-### Enable Verbose Logging
-
-Add console.error statements (they go to stderr, not stdout):
-
-```typescript
-console.error("DEBUG: Tool called with args:", args);
-```
-
-### Test Individual Components
-
-```bash
-# Test configuration loading
-node -e "const {ConfigLoader} = require('./dist/config/loader.js'); console.log(ConfigLoader.load())"
-
-# Test permission filter
-node -e "const {PermissionFilter} = require('./dist/permissions/filter.js'); const f = new PermissionFilter({mode:'readonly',whitelist:[],blacklist:[]}); console.log(f.isToolAllowed('jira_search_issues'))"
-```
-
-### Run Unit Tests
-
-```bash
-npm test
-```
-
-### Test Specific Test File
-
-```bash
-node --test tests/permissions/filter.test.ts
-```
-
----
-
-## Common Issues
-
-### Issue: "Command not found"
-
-**Solution:** Use absolute path in Claude Desktop config:
-```json
-"args": ["/Users/yourname/projects/jicon/dist/index.js"]
-```
-
-### Issue: "No services configured"
-
-**Solution:** Check your `.jicon.json` or environment variables are set correctly.
-
-### Issue: Server not appearing in Claude Desktop
-
-**Solution:**
-1. Check config file syntax (valid JSON)
-2. Restart Claude Desktop completely
-3. Check logs for errors
-4. Verify the `command` path is correct
-
-### Issue: Permission denied errors
-
-**Solution:** Check your `permissions` configuration in `.jicon.json`.
-
-### Issue: Changes not taking effect
-
-**Solution:**
-1. Run `npm run build` after code changes
-2. Completely quit and restart Claude Desktop
-3. Clear Claude Desktop cache if needed
-
----
-
-## Testing Checklist
-
-Before committing changes:
-
-- [ ] `npm run build` succeeds
-- [ ] `npm test` passes
-- [ ] Server starts without errors
-- [ ] Can list tools via MCP Inspector
-- [ ] Can execute tools in Claude Desktop
-- [ ] Permission system works as expected
-- [ ] Error messages are clear and helpful
-- [ ] Config hierarchy works (project > home > env)
-
----
-
-## Advanced: Testing with Multiple Configurations
-
-Create a test script to quickly switch configs:
-
-```bash
-#!/bin/bash
-# test-config.sh
-
-case $1 in
-  "full")
-    cp .jicon.json.example .jicon.json
-    ;;
-  "readonly")
-    cp .jicon.json.readonly .jicon.json
-    ;;
-  "custom")
-    cp .jicon.json.custom .jicon.json
-    ;;
-  *)
-    echo "Usage: ./test-config.sh [full|readonly|custom]"
-    exit 1
-    ;;
-esac
-
-echo "Switched to $1 mode. Restart Claude Desktop to apply."
-```
-
----
-
-## Testing with CI/CD
-
-For automated testing, you can use the MCP test utilities:
-
-```bash
-# Run integration tests (coming soon)
-npm run test:integration
-
-# Test against mock Jira/Confluence servers
-npm run test:e2e
-```
-
----
-
-## Need Help?
-
-- Check [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines
-- See [README.md](README.md) for configuration examples
-- Open an issue on GitHub for bugs
-- Use GitHub Discussions for questions
-
----
-
-**Happy Testing! 🚀**

package/JIRA_API_ANALYSIS.md

@@ -1,275 +0,0 @@
-# Jira API Compatibility Analysis
-
-**Date**: 2025-11-12
-**Analysis**: Jira REST API implementation vs. latest official documentation
-**Target**: Jira Server/Data Center and Jira Cloud
-
----
-
-## Executive Summary
-
-The current Jira implementation is **FULLY COMPATIBLE** with **Jira Server/Data Center** (versions 8.x, 9.x, and latest) but has **LIMITED COMPATIBILITY** with **Jira Cloud**. While the documentation claims to support both platforms, the implementation uses Server/Data Center-specific patterns that will fail on Cloud instances.
-
-### Key Findings
-
-| Component | Server/Data Center | Cloud | Status |
-|-----------|-------------------|-------|--------|
-| Core API Version | `/rest/api/2/` ✅ | `/rest/api/3/` ❌ | **Partial** |
-| Agile API Version | `/rest/agile/1.0/` ✅ | `/rest/agile/1.0/` ✅ | **Good** |
-| User References | `{ name: "username" }` ✅ | `{ accountId: "..." }` ❌ | **Incompatible** |
-| Authentication | Basic + Bearer ✅ | Basic (email + token) ✅ | **Good** |
-| Search Method | POST ✅ | POST ✅ | **Good** |
-
----
-
-## Detailed Analysis
-
-### 1. Core API Endpoints (`/rest/api/2/`)
-
-#### Status: ✅ CURRENT for Server/Data Center
-
-**Current Implementation**: `/rest/api/2/`
-
-**Finding**: The implementation correctly uses `/rest/api/2/` for all core operations:
-- Issue search: `/rest/api/2/search` (line 42 in client.ts)
-- Issue operations: `/rest/api/2/issue/{key}`
-- Comments: `/rest/api/2/issue/{key}/comment`
-- Projects: `/rest/api/2/project`
-- Transitions: `/rest/api/2/issue/{key}/transitions`
-- Issue links: `/rest/api/2/issueLink`
-
-**Recommendation**: ✅ **No changes needed** for Server/Data Center. This is the current and correct API version for Jira Server/Data Center 8.x, 9.x, and latest (11.2.0).
-
-**Note for Cloud**: Jira Cloud uses `/rest/api/3/` as its primary API version, though `/rest/api/2/` is still supported for backward compatibility. For full Cloud support, consider adding v3 endpoints.
-
----
-
-### 2. Agile API Endpoints (`/rest/agile/1.0/`)
-
-#### Status: ✅ CURRENT for both Server/Data Center and Cloud
-
-**Current Implementation**: `/rest/agile/1.0/`
-
-**Finding**: The implementation correctly uses `/rest/agile/1.0/` for all Agile operations:
-- Boards: `/rest/agile/1.0/board/{id}` (line 268)
-- Sprints: `/rest/agile/1.0/board/{id}/sprint` (line 282)
-- Sprint issues: `/rest/agile/1.0/sprint/{id}/issue` (line 299)
-
-**Verification**: Checked against latest Jira Agile Data Center 9.17.0 REST API documentation. Version 1.0 is still current across all versions.
-
-**Recommendation**: ✅ **No changes needed**. This is correct and not obsolete.
-
----
-
-### 3. Issue Search Method (GET vs POST)
-
-#### Status: ✅ OPTIMAL
-
-**Current Implementation**: POST `/rest/api/2/search`
-
-**Finding**: The implementation uses POST for issue search (line 42 in client.ts):
-```typescript
-return this.http.post<JiraSearchResult>("/rest/api/2/search", params);
-```
-
-**Best Practice**: According to official documentation:
-- GET is suitable for simple queries
-- POST is recommended when JQL is large to avoid URL length limitations
-
-**Recommendation**: ✅ **No changes needed**. Using POST is the safer and more robust approach.
-
----
-
-### 4. User Field Format (CRITICAL ISSUE)
-
-#### Status: ❌ INCOMPATIBLE with Jira Cloud
-
-**Current Implementation**: `{ name: "username" }`
-
-**Code Location**: `src/jira/client.ts:92`
-```typescript
-if (issueData.assignee) {
-  fields.assignee = { name: issueData.assignee };
-}
-```
-
-**Problem**: This format only works for Jira Server/Data Center. Jira Cloud requires:
-```typescript
-fields.assignee = { accountId: "5b10ac8d82e05b22cc7d4ef5" };
-```
-
-**Background**:
-- **Pre-GDPR (before 2018)**: Jira used `name` and `key` fields for users
-- **Post-GDPR (2018+)**: Jira Cloud deprecated `name`/`key` fields
-- **Current (2024)**: Cloud requires `accountId`, Server/Data Center still uses `name`
-
-**Impact**:
-- ❌ Creating/updating issues with assignee will fail on Jira Cloud
-- ✅ Works correctly on Server/Data Center
-
-**Recommendation**: Implement Cloud detection and conditional field format:
-
-```typescript
-// Detect if Cloud instance
-private isCloudInstance(): boolean {
-  return this.config.url.includes('.atlassian.net');
-}
-
-// In createIssue method:
-if (issueData.assignee) {
-  if (this.isCloudInstance()) {
-    fields.assignee = { accountId: issueData.assignee };
-  } else {
-    fields.assignee = { name: issueData.assignee };
-  }
-}
-```
-
-**Alternative**: Document that assignee parameter should be formatted according to instance type, and users should provide the correct identifier format.
-
----
-
-### 5. Other Field Formats
-
-#### Status: ✅ CORRECT
-
-**Current Implementation**:
-```typescript
-project: { key: issueData.projectKey }     // ✅ Correct
-issuetype: { name: issueData.issueType }   // ✅ Correct
-priority: { name: issueData.priority }     // ✅ Correct
-components: issueData.components.map(name => ({ name })) // ✅ Correct
-```
-
-**Finding**: All other field formats follow the correct patterns for both Cloud and Server/Data Center.
-
-**Recommendation**: ✅ **No changes needed**.
-
----
-
-### 6. Authentication Methods
-
-#### Status: ✅ GOOD
-
-**Current Implementation**: Supports both Basic Auth and Bearer Auth
-
-**Server/Data Center**:
-- ✅ Basic Auth: username + password/token
-- ✅ Bearer Auth: Personal Access Token (PAT) for 8.14+
-
-**Cloud**:
-- ✅ Basic Auth: email + API token
-
-**Recommendation**: ✅ **No changes needed**. Authentication is correctly implemented.
-
----
-
-### 7. Deprecated Features Check
-
-#### OAuth 1.0a
-- **Status**: Deprecated in Jira Agile API
-- **Impact**: Not applicable (we don't use OAuth)
-
-#### createmeta Endpoint
-- **Status**: Removed in Jira 9.0 due to performance issues
-- **Impact**: Not applicable (we don't use this endpoint)
-
-#### User Privacy API
-- **Status**: `name` field deprecated in Cloud only
-- **Impact**: ❌ Affects our assignee field implementation (see section 4)
-
----
-
-## Missing Modern Features
-
-While the implementation is not using obsolete APIs, there are some modern features that could be added:
-
-1. **Issue Properties API** - Store custom key-value data on issues
-2. **Bulk Operations** - Update multiple issues in one call
-3. **Advanced Search Features** - More sophisticated JQL query building
-4. **Webhooks** - Real-time event notifications
-5. **User Search API** - Find users by email/name to get accountId (critical for Cloud support)
-
----
-
-## Recommendations
-
-### Priority 1: Critical (Cloud Compatibility)
-
-1. **Add Cloud/Data Center Detection**
-   ```typescript
-   private isCloudInstance(): boolean {
-     return this.config.url.includes('.atlassian.net');
-   }
-   ```
-
-2. **Fix Assignee Field Format**
-   - Implement conditional formatting based on instance type
-   - Add user search tool to get accountId on Cloud instances
-   - Update documentation to clarify assignee parameter format
-
-3. **Update Documentation**
-   - Clarify that current implementation is optimized for Server/Data Center
-   - Document Cloud limitations
-   - Provide examples for both platforms
-
-### Priority 2: Enhancement (Optional)
-
-1. **Add User Search Tool**
-   ```typescript
-   async searchUsers(query: string): Promise<User[]> {
-     const endpoint = this.isCloudInstance()
-       ? '/rest/api/3/user/search'
-       : '/rest/api/2/user/search';
-     return this.http.get(endpoint, { params: { query } });
-   }
-   ```
-
-2. **Consider Cloud v3 API Support**
-   - Add optional v3 endpoint support for Cloud instances
-   - Maintain v2 backward compatibility
-
-3. **Add Bulk Operations**
-   - Implement bulk update/transition endpoints
-   - Reduce API calls for batch operations
-
----
-
-## Conclusion
-
-### Current Status: ✅ FULLY COMPATIBLE with Server/Data Center
-
-The Jira implementation uses **current, non-obsolete APIs** for Jira Server/Data Center:
-- ✅ `/rest/api/2/` is the correct version (not obsolete)
-- ✅ `/rest/agile/1.0/` is the current Agile API version
-- ✅ Field formats are correct for Server/Data Center
-- ✅ Authentication methods are modern and secure
-- ✅ Search implementation follows best practices
-
-### Cloud Compatibility: ⚠️ LIMITED
-
-The implementation has **limited Cloud support**:
-- ❌ User field format incompatible (`name` vs `accountId`)
-- ⚠️ Using v2 API instead of recommended v3 for Cloud
-- ✅ Authentication works correctly
-- ✅ Most read operations work correctly
-
-### Final Recommendation
-
-**If targeting Server/Data Center only**: ✅ **NO CHANGES NEEDED** - implementation is current and correct.
-
-**If targeting both Cloud and Data Center**: ⚠️ **UPDATES REQUIRED**:
-1. Implement Cloud detection
-2. Fix user field formats
-3. Add user search capability
-4. Update documentation to clarify platform-specific behavior
-
----
-
-## References
-
-- [Jira Data Center REST API v11.2.0](https://developer.atlassian.com/server/jira/platform/rest/v10000/)
-- [Jira Cloud REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
-- [Jira Agile Data Center 9.17.0 REST API](https://docs.atlassian.com/jira-software/REST/9.17.0/)
-- [Jira REST API Examples](https://developer.atlassian.com/server/jira/platform/jira-rest-api-examples/)
-- [GDPR User API Migration](https://community.atlassian.com/t5/Jira-questions/What-value-should-be-used-in-assignee-filed-while-creating-issue/qaq-p/1352474)