@crypto512/jicon-mcp 0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,400 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jicon Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# Jicon - Jira & Confluence MCP Server
+
+[![npm version](https://badge.fury.io/js/%40crypto512%2Fjicon-mcp.svg)](https://badge.fury.io/js/%40crypto512%2Fjicon-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> A comprehensive Model Context Protocol (MCP) server for seamless integration with Atlassian Jira and Confluence.
+
+## Quick Start
+
+```bash
+# Run with npx (no installation required)
+npx @crypto512/jicon-mcp
+
+# Or install globally
+npm install -g @crypto512/jicon-mcp
+```
+
+## What is Jicon?
+
+Jicon is an MCP server that enables AI assistants like Claude to interact with your Jira and Confluence instances. It provides 28 powerful tools for:
+
+- 🎫 **Jira**: Issue management, searching, project operations, Agile boards, sprints
+- 📄 **Confluence**: Page management, content search, spaces, attachments, comments
+
+## Features at a Glance
+
+### Jira (15 Tools)
+- Search issues with JQL
+- Create, update, and transition issues
+- Manage comments and links
+- Access boards and sprints
+- View projects and metadata
+
+### Confluence (13 Tools)
+- Search content with CQL
+- Create and update pages
+- Navigate page hierarchies
+- Manage attachments
+- Add and view comments
+
+## Configuration
+
+### Configuration with `.jicon.json` (Recommended)
+
+Jicon supports a flexible configuration hierarchy with permission control:
+
+**Configuration Priority:**
+1. `.jicon.json` (project root) - **Highest priority**
+2. `$HOME/.config/jicon/jicon.json` (user config) - Medium priority
+3. Environment variables - Lowest priority (legacy)
+
+**Create `.jicon.json` in your project root:**
+
+```json
+{
+  "jira": {
+    "url": "https://jira.example.com",
+    "username": "your-email@example.com",
+    "token": "your-api-token"
+  },
+  "confluence": {
+    "url": "https://confluence.example.com",
+    "username": "your-email@example.com",
+    "token": "your-api-token"
+  },
+  "permissions": {
+    "mode": "full"
+  }
+}
+```
+
+**⚠️ Important:** Add `.jicon.json` to your `.gitignore` to avoid committing credentials!
+
+### Permission Modes
+
+Control which tools are allowed to execute:
+
+#### 1. **Full Access** (default)
+```json
+{ "permissions": { "mode": "full" } }
+```
+All 28 tools are available.
+
+#### 2. **Read-Only Mode**
+```json
+{ "permissions": { "mode": "readonly" } }
+```
+Only read operations (18 tools: 10 Jira + 8 Confluence).
+
+#### 3. **Custom Mode** with Virtual Actions
+
+Simplify configuration with **virtual actions** that group related tools:
+
+**Virtual Actions Available:**
+- `jira_read` - All 10 Jira read tools
+- `jira_write` - All 5 Jira write tools
+- `jira_all` - All 15 Jira tools
+- `confluence_read` - All 8 Confluence read tools
+- `confluence_write` - All 5 Confluence write tools
+- `confluence_all` - All 13 Confluence tools
+
+**Example: Read-only access to both services**
+```json
+{
+  "permissions": {
+    "mode": "custom",
+    "whitelist": ["jira_read", "confluence_read"]
+  }
+}
+```
+
+**Example: Full Jira + Confluence read-only**
+```json
+{
+  "permissions": {
+    "mode": "custom",
+    "whitelist": ["jira_all", "confluence_read"]
+  }
+}
+```
+
+**Example: Specific tools only**
+```json
+{
+  "permissions": {
+    "mode": "custom",
+    "whitelist": [
+      "jira_search_issues",
+      "jira_get_issue",
+      "jira_create_issue",
+      "confluence_get_page"
+    ]
+  }
+}
+```
+
+**Example: Blacklist dangerous operations**
+```json
+{
+  "permissions": {
+    "mode": "custom",
+    "blacklist": ["confluence_delete_page"]
+  }
+}
+```
+
+See [`.jicon.json.example`](.jicon.json.example), [`.jicon.json.readonly`](.jicon.json.readonly), and [`.jicon.json.custom`](.jicon.json.custom) for more examples.
+
+### Environment Variables (Legacy)
+
+For Claude Desktop, add to config file:
+
+**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "jicon": {
+      "command": "npx",
+      "args": ["-y", "@crypto512/jicon-mcp"],
+      "env": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token",
+        "CONFLUENCE_URL": "https://confluence.example.com",
+        "CONFLUENCE_USERNAME": "your-email@example.com",
+        "CONFLUENCE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Example Usage
+
+Once configured, you can ask Claude to:
+
+- *"Find all high-priority bugs assigned to me in the PROJ project"*
+- *"Create a new task for implementing the login feature"*
+- *"Show me the current sprint's progress"*
+- *"Update the API documentation page in Confluence"*
+- *"Search for pages about authentication in the DOCS space"*
+
+## Documentation
+
+- **[CLAUDE.md](CLAUDE.md)** - Complete functional specification
+- **[TOOL_LIST.md](TOOL_LIST.md)** - Comprehensive tool reference with examples
+- **[API Documentation](docs/api.md)** - Detailed API documentation (coming soon)
+
+## Tool Categories
+
+### Jira Tools
+| Category | Tools |
+|----------|-------|
+| **Search & Retrieval** | `jira_search_issues`, `jira_get_issue`, `jira_get_issue_comments` |
+| **Issue Management** | `jira_create_issue`, `jira_update_issue`, `jira_transition_issue` |
+| **Collaboration** | `jira_add_comment`, `jira_link_issues`, `jira_get_issue_watchers` |
+| **Projects** | `jira_list_projects`, `jira_get_project` |
+| **Agile** | `jira_get_board`, `jira_get_sprints`, `jira_get_sprint_issues` |
+| **Workflow** | `jira_get_transitions` |
+
+### Confluence Tools
+| Category | Tools |
+|----------|-------|
+| **Search & Retrieval** | `confluence_search_content`, `confluence_get_page`, `confluence_get_page_by_title` |
+| **Page Management** | `confluence_create_page`, `confluence_update_page`, `confluence_delete_page` |
+| **Spaces** | `confluence_list_spaces`, `confluence_get_space` |
+| **Navigation** | `confluence_get_page_children` |
+| **Collaboration** | `confluence_add_comment`, `confluence_get_comments` |
+| **Attachments** | `confluence_upload_attachment`, `confluence_list_attachments` |
+
+## Requirements
+
+- Node.js 18 or higher
+- Jira Server/Data Center or Jira Cloud instance
+- Confluence Server/Data Center or Confluence Cloud instance
+- Valid API tokens or Personal Access Tokens
+
+## Authentication
+
+### Jira/Confluence Cloud
+Generate an API token from your Atlassian account:
+1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+2. Create a new API token
+3. Use your email as username and the token as password
+
+### Jira/Confluence Data Center
+Generate a Personal Access Token (PAT):
+1. Go to your profile settings
+2. Navigate to "Personal Access Tokens"
+3. Create a new token with required permissions
+
+## Security Best Practices
+
+- ✅ Store credentials in environment variables
+- ✅ Use API tokens with minimal required permissions
+- ✅ Regularly rotate API tokens
+- ✅ Never commit credentials to version control
+- ✅ Use read-only tokens for search/read operations
+
+## Development Status
+
+- ✅ **Specification Complete** - Functional spec and tool list defined
+- ✅ **Implementation Complete** - All 28 tools implemented
+- ✅ **Testing** - 86 tests passing
+- ✅ **Configuration System** - Flexible .jicon.json with permissions
+- 📦 **Publishing** - Ready for npm publish
+
+## Roadmap
+
+### Phase 1: Core Implementation ✅ **COMPLETED**
+- ✅ Project setup and structure
+- ✅ Jira API client implementation (310 lines, 15 tools)
+- ✅ Confluence API client implementation (281 lines, 13 tools)
+- ✅ MCP server implementation (179 lines)
+- ✅ Basic testing (86 tests, 100% pass rate)
+- ✅ Configuration system (.jicon.json with hierarchy)
+- ✅ Permission system (full, readonly, custom modes)
+- ✅ Virtual actions (jira_read, jira_all, confluence_read, etc.)
+- ✅ Development and contributing guides
+
+### Phase 2: Enhancement (In Progress)
+- ✅ Advanced error handling (implemented)
+- [ ] Rate limiting and caching
+- [ ] Integration tests with mock servers
+- ✅ Documentation examples (DEVELOPMENT.md added)
+- [ ] CI/CD pipeline
+- [ ] npm package publishing
+
+### Phase 3: Advanced Features (Planned)
+- [ ] Bulk operations
+- [ ] Custom field templates
+- [ ] Webhook support
+- [ ] Multi-instance support
+- [ ] CLI tool for configuration testing
+- [ ] Performance optimizations
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 🐛 **Issues**: [GitHub Issues](https://github.com/crypto512/jicon/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/crypto512/jicon/discussions)
+- 📖 **Documentation**: [GitHub Repository](https://github.com/crypto512/jicon)
+
+## Acknowledgments
+
+- Built on [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
+- Powered by Atlassian APIs
+- Inspired by the community's need for better Jira/Confluence integration
+
+---
+
+**Made with ❤️ for developers who work with Jira and Confluence**