agentek-youtrack-mcp 1.0.0

package/README.npm.md

@@ -0,0 +1,436 @@
+# YouTrack MCP Server
+
+[![npm version](https://badge.fury.io/js/agentek-youtrack-mcp.svg)](https://www.npmjs.com/package/agentek-youtrack-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/agentek-youtrack-mcp.svg)](https://www.npmjs.com/package/agentek-youtrack-mcp)
+
+A Model Context Protocol (MCP) server for JetBrains YouTrack, enabling seamless integration with Claude Desktop and other MCP clients.
+
+## Quick Start
+
+Choose your preferred installation method:
+
+### Option 1: npm/Node.js (Recommended)
+
+**Installation:**
+```bash
+# Install globally
+npm install -g agentek-youtrack-mcp
+
+# Or use with npx (no installation required)
+npx agentek-youtrack-mcp
+```
+
+**Usage:**
+```bash
+# Run with stdio transport (for Claude Desktop)
+npx agentek-youtrack-mcp
+
+# Run with HTTP transport
+npx agentek-youtrack-mcp --http --port 8000
+
+# Show help
+npx agentek-youtrack-mcp --help
+```
+
+### Option 2: Docker
+
+**Using Docker Hub:**
+```bash
+# Use the latest stable release
+docker run --rm \
+  -e YOUTRACK_URL="https://your.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest
+
+# Or use the latest development build
+docker run --rm \
+  -e YOUTRACK_URL="https://your.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:1.11.1_wip
+```
+
+**Available Docker Tags:**
+- `latest` - Latest stable release
+- `1.11.1` - Specific version tags  
+- `1.11.1_wip` - Work-in-progress builds from main branch
+- `pr-<number>` - Pull request builds for testing
+
+## Configuration
+
+### Environment Variables
+
+Set these environment variables for both npm and Docker options:
+
+```bash
+export YOUTRACK_URL="https://your.youtrack.cloud"
+export YOUTRACK_API_TOKEN="your-token"
+export YOUTRACK_VERIFY_SSL="true"  # Optional, default: true
+```
+
+### Claude Desktop Integration
+
+Choose your preferred method:
+
+#### Using npm/Node.js:
+```json
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "npx",
+      "args": ["agentek-youtrack-mcp"],
+      "env": {
+        "YOUTRACK_URL": "https://your.youtrack.cloud",
+        "YOUTRACK_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+#### Using Docker Hub:
+```json
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "docker",
+      "args": [
+        "run", "--rm",
+        "-e", "YOUTRACK_URL=https://your.youtrack.cloud",
+        "-e", "YOUTRACK_API_TOKEN=your-token",
+        "windbit/agentek-youtrack-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+#### Using GitHub Container Registry:
+```json
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "docker",
+      "args": [
+        "run", "--rm",
+        "-e", "YOUTRACK_URL=https://your.youtrack.cloud",
+        "-e", "YOUTRACK_API_TOKEN=your-token",
+        "ghcr.io/windbit/agentek-youtrack-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+#### Using GitHub Packages npm:
+```json
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "npx",
+      "args": ["@windbit/agentek-youtrack-mcp"],
+      "env": {
+        "YOUTRACK_URL": "https://your.youtrack.cloud",
+        "YOUTRACK_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+## Features
+
+- **Issue Management**: Create, read, update, and delete YouTrack issues
+- **Project Management**: Access project information and custom fields
+- **Search Capabilities**: Advanced search with filters and custom fields
+- **User Management**: Retrieve user information and permissions
+- **Attachment Support**: Download, process, and delete issue attachments (up to 10MB)
+- **Multi-Platform Support**: ARM64/Apple Silicon and AMD64 architecture support
+
+## Requirements
+
+### For npm/Node.js option:
+- **Node.js**: 18.0.0 or higher
+- **Python**: 3.8 or higher (automatically detected)
+- **YouTrack**: Cloud or Server instance with API access
+
+### For Docker option:
+- **Docker**: Latest version
+- **YouTrack**: Cloud or Server instance with API access
+
+*Note: Docker option includes all dependencies pre-installed*
+
+## API Commands
+
+Once configured, you can use these commands in Claude:
+
+- Create, update, and manage YouTrack issues
+- Search issues with advanced filters
+- Access project information and custom fields
+- Download, analyze, and delete issue attachments
+- Manage user permissions and assignments
+
+## CLI Options
+
+```
+Usage:
+  npx agentek-youtrack-mcp [options] [-- server-args]
+
+Options:
+  --help, -h           Show help message
+  --version, -v        Show version information
+  --info               Show server information
+  --stdio              Use stdio transport (default)
+  --http               Use HTTP transport
+  --host <host>        Host to bind HTTP server (default: 0.0.0.0)
+  --port <port>        Port for HTTP server (default: 8000)
+
+Environment Variables:
+  YOUTRACK_URL          Your YouTrack instance URL (required)
+  YOUTRACK_API_TOKEN    Your YouTrack API token (required)
+  YOUTRACK_VERIFY_SSL   Verify SSL certificates (default: true)
+```
+
+## Examples
+
+### Basic Usage
+
+#### npm/Node.js:
+```bash
+# Set environment variables
+export YOUTRACK_URL="https://prodcamp.youtrack.cloud"
+export YOUTRACK_API_TOKEN="your-token"
+
+# Run the server
+npx agentek-youtrack-mcp
+```
+
+#### Docker Hub:
+```bash
+# Run with environment variables
+docker run --rm \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest
+```
+
+#### GitHub Container Registry:
+```bash
+# Run with environment variables
+docker run --rm \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  ghcr.io/windbit/agentek-youtrack-mcp:latest
+```
+
+#### GitHub Packages npm:
+```bash
+# Set up GitHub registry (one-time setup)
+npm config set @windbit:registry https://npm.pkg.github.com
+
+# Run with npx
+npx @windbit/agentek-youtrack-mcp
+```
+
+### HTTP Mode
+
+#### npm/Node.js:
+```bash
+# Start HTTP server on port 8000
+npx agentek-youtrack-mcp --http --port 8000
+
+# Test the server
+curl http://localhost:8000/api/tools
+```
+
+#### Docker Hub:
+```bash
+# Start HTTP server with port mapping
+docker run --rm -p 8000:8000 \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest --transport http --host 0.0.0.0
+
+# Test the server
+curl http://localhost:8000/api/tools
+```
+
+#### GitHub Container Registry:
+```bash
+# Start HTTP server with port mapping
+docker run --rm -p 8000:8000 \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  ghcr.io/windbit/agentek-youtrack-mcp:latest --transport http --host 0.0.0.0
+
+# Test the server
+curl http://localhost:8000/api/tools
+```
+
+#### GitHub Packages npm:
+```bash
+# Start HTTP server
+npx @windbit/agentek-youtrack-mcp --http --port 8000
+
+# Test the server
+curl http://localhost:8000/api/tools
+```
+
+### Development Mode
+
+#### npm/Node.js:
+```bash
+# Run with debug logging
+npx agentek-youtrack-mcp -- --log-level DEBUG
+```
+
+#### Docker Hub:
+```bash
+# Run with debug logging
+docker run --rm \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest --log-level DEBUG
+```
+
+#### GitHub Container Registry:
+```bash
+# Run with debug logging
+docker run --rm \
+  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  ghcr.io/windbit/agentek-youtrack-mcp:latest --log-level DEBUG
+```
+
+#### GitHub Packages npm:
+```bash
+# Run with debug logging
+npx @windbit/agentek-youtrack-mcp -- --log-level DEBUG
+```
+
+## Troubleshooting
+
+### npm/Node.js Issues
+
+#### Python Not Found
+If you get a "Python not found" error:
+
+```bash
+# Install Python 3.8+
+# macOS with Homebrew:
+brew install python
+
+# Ubuntu/Debian:
+sudo apt-get install python3
+
+# Windows: Download from python.org
+```
+
+#### Permission Errors
+```bash
+# Check your YouTrack API token
+npx agentek-youtrack-mcp --info
+
+# Verify your environment variables
+echo $YOUTRACK_URL
+echo $YOUTRACK_API_TOKEN
+```
+
+### Docker Issues
+
+#### Container Won't Start
+```bash
+# Check Docker is running
+docker --version
+
+# Check container logs
+docker run --rm \
+  -e YOUTRACK_URL="https://your.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest --version
+```
+
+#### Port Already in Use
+```bash
+# Use a different port
+docker run --rm -p 8001:8000 \
+  -e YOUTRACK_URL="https://your.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:latest --transport http
+```
+
+#### GitHub Container Registry Authentication
+```bash
+# If you get pull errors from ghcr.io, you might need to authenticate
+docker login ghcr.io
+
+# Then try pulling again
+docker pull ghcr.io/windbit/agentek-youtrack-mcp:latest
+```
+
+### GitHub Packages Issues
+
+#### npm Registry Configuration
+```bash
+# If @windbit/agentek-youtrack-mcp is not found, configure the registry
+npm config set @windbit:registry https://npm.pkg.github.com
+
+# You might need authentication for GitHub Packages npm
+npm login --registry=https://npm.pkg.github.com
+```
+
+#### Package Not Found
+If GitHub Packages npm shows "package not found":
+- The package is published only on releases
+- Check if a release has been created
+- Fallback to npmjs.org version: `npm install -g agentek-youtrack-mcp`
+
+### Common Issues (Both Options)
+
+#### Connection Issues
+If you can't connect to YouTrack:
+
+- Verify your YouTrack URL is correct
+- Check that your API token has proper permissions
+- Ensure your network allows connections to YouTrack
+- Try testing the API token manually:
+  ```bash
+  curl -H "Authorization: Bearer your-token" \
+       "https://your.youtrack.cloud/api/admin/projects"
+  ```
+
+## Which Option Should I Choose?
+
+### Choose **npm/Node.js** if you:
+- ✅ Already have Node.js installed
+- ✅ Want faster startup times
+- ✅ Prefer lighter resource usage
+- ✅ Need to modify or debug the server
+
+**Registry Options:**
+- **npmjs.org** (recommended): `agentek-youtrack-mcp` - Better discovery, wider usage
+- **GitHub Packages**: `@windbit/agentek-youtrack-mcp` - Integrated with GitHub, requires registry config
+
+### Choose **Docker** if you:
+- ✅ Want isolated, consistent environments
+- ✅ Don't want to install Node.js/Python
+- ✅ Are running in containerized infrastructure
+- ✅ Want guaranteed dependency compatibility
+
+**Registry Options:**
+- **Docker Hub** (recommended): `windbit/agentek-youtrack-mcp` - Faster, no auth required
+- **GitHub Container Registry**: `ghcr.io/windbit/agentek-youtrack-mcp` - Integrated with GitHub, may require auth
+
+## Support
+
+- **GitHub**: [Issues and bug reports](https://github.com/windbit/agentek-youtrack-mcp/issues)
+- **Documentation**: [Full documentation](https://github.com/windbit/agentek-youtrack-mcp)
+
+### Package Registries
+- **Docker Hub**: [windbit/agentek-youtrack-mcp](https://hub.docker.com/r/windbit/agentek-youtrack-mcp)
+- **GitHub Container Registry**: [ghcr.io/windbit/agentek-youtrack-mcp](https://github.com/windbit/agentek-youtrack-mcp/pkgs/container/youtrack-mcp)
+- **npmjs.org**: [agentek-youtrack-mcp](https://www.npmjs.com/package/agentek-youtrack-mcp)
+- **GitHub Packages npm**: [@windbit/agentek-youtrack-mcp](https://github.com/windbit/agentek-youtrack-mcp/pkgs/npm/%40windbit%2Fagentek-youtrack-mcp)
+
+## License
+
+MIT

package/dist/bin/youtrack-mcp.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+import YouTrackMCPServer from '../index.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * YouTrack MCP Server CLI
+ * 
+ * This CLI tool allows you to run the YouTrack MCP server from the command line
+ * after installing it via npm.
+ */
+
+function showHelp() {
+  console.log(`
+📋 YouTrack MCP Server CLI
+
+Usage:
+  npx agentek-youtrack-mcp [options] [-- server-args]
+  agentek-youtrack-mcp [options] [-- server-args]
+
+Options:
+  --help, -h           Show this help message
+  --version, -v        Show version information
+  --info               Show server information
+  --stdio              Use stdio transport (default)
+  --http               Use HTTP transport with --host and --port
+  --host <host>        Host to bind HTTP server (default: 0.0.0.0)
+  --port <port>        Port for HTTP server (default: 8000)
+
+Environment Variables:
+  YOUTRACK_URL          Your YouTrack instance URL (required)
+  YOUTRACK_API_TOKEN    Your YouTrack API token (required)
+  YOUTRACK_VERIFY_SSL   Verify SSL certificates (default: true)
+
+Examples:
+  # Run with stdio transport (for Claude Desktop)
+  npx agentek-youtrack-mcp
+
+  # Run with HTTP transport
+  npx agentek-youtrack-mcp --http --port 8000
+
+  # Pass arguments to the Python server
+  npx agentek-youtrack-mcp -- --log-level DEBUG
+
+  # Set environment variables inline
+  YOUTRACK_URL=https://your.youtrack.cloud YOUTRACK_API_TOKEN=your-token npx agentek-youtrack-mcp
+
+Configuration for Claude Desktop:
+Add this to your Claude Desktop config:
+{
+  "mcpServers": {
+    "youtrack": {
+      "command": "npx",
+      "args": ["agentek-youtrack-mcp"],
+      "env": {
+        "YOUTRACK_URL": "https://your.youtrack.cloud",
+        "YOUTRACK_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+`);
+}
+
+function showVersion() {
+  try {
+    const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    console.log(`YouTrack MCP Server v${packageJson.version}`);
+  } catch (error) {
+    console.log('YouTrack MCP Server v1.11.1');
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  // Handle help and version flags
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+  
+  if (args.includes('--version') || args.includes('-v')) {
+    showVersion();
+    return;
+  }
+
+  try {
+    const server = new YouTrackMCPServer();
+    
+    if (args.includes('--info')) {
+      console.log('📊 Server Information:');
+      console.log(JSON.stringify(server.getInfo(), null, 2));
+      return;
+    }
+
+    // Parse arguments
+    const serverArgs = [];
+    let useHttp = false;
+    let host = '0.0.0.0';
+    let port = '8000';
+    
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      
+      if (arg === '--') {
+        // Everything after -- goes to the Python server
+        serverArgs.push(...args.slice(i + 1));
+        break;
+      }
+      
+      switch (arg) {
+        case '--stdio':
+          useHttp = false;
+          break;
+        case '--http':
+          useHttp = true;
+          break;
+        case '--host':
+          host = args[++i];
+          break;
+        case '--port':
+          port = args[++i];
+          break;
+        default:
+          // Pass unknown args to the Python server
+          serverArgs.push(arg);
+      }
+    }
+
+    // Configure transport
+    if (useHttp) {
+      serverArgs.push('--transport', 'http', '--host', host);
+      console.log(`🌐 Starting HTTP server on http://${host}:${port}`);
+    } else {
+      serverArgs.push('--transport', 'stdio');
+      console.log('📡 Starting stdio transport (for Claude Desktop)');
+    }
+
+    // Start the server
+    await server.start(serverArgs);
+    
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error('❌ Unexpected error:', error);
+  process.exit(1);
+}); 

package/dist/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * YouTrack MCP Server Node.js Wrapper
+ * 
+ * This wrapper allows the Python-based YouTrack MCP server to be installed
+ * and executed via npm/npx, following MCP packaging conventions.
+ */
+class YouTrackMCPServer {
+  constructor() {
+    this.pythonPath = null;
+    this.serverPath = null;
+    this.setupPaths();
+  }
+
+  setupPaths() {
+    // Use python3 by default, fall back to python
+    // The actual existence check will happen when we try to run it
+    this.pythonPath = 'python3';
+
+    // Find the server main.py file
+    const possiblePaths = [
+      join(__dirname, 'python', 'main.py'),           // From dist/
+      join(__dirname, '..', 'python', 'main.py'), // From python/ directory
+      join(__dirname, 'main.py')                   // Current directory
+    ];
+
+    for (const path of possiblePaths) {
+      if (existsSync(path)) {
+        this.serverPath = path;
+        break;
+      }
+    }
+
+    if (!this.serverPath) {
+      throw new Error('YouTrack MCP server main.py not found');
+    }
+  }
+
+  /**
+   * Start the YouTrack MCP server
+   * @param {string[]} args - Command line arguments to pass to the Python server
+   * @param {Object} options - Additional options
+   * @returns {Promise<void>}
+   */
+  async start(args = [], options = {}) {
+    console.log('🚀 Starting YouTrack MCP Server...');
+    
+    // Validate environment variables
+    this.validateEnvironment();
+
+    const pythonArgs = [this.serverPath, ...args];
+    
+    console.log(`📍 Using Python: ${this.pythonPath}`);
+    console.log(`📍 Server path: ${this.serverPath}`);
+    console.log(`📍 Arguments: ${pythonArgs.slice(1).join(' ')}`);
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(this.pythonPath, pythonArgs, {
+        stdio: options.stdio || 'inherit',
+        env: { ...process.env, ...options.env },
+        cwd: options.cwd || process.cwd()
+      });
+
+      child.on('error', (error) => {
+        console.error('❌ Failed to start YouTrack MCP server:', error.message);
+        reject(error);
+      });
+
+      child.on('exit', (code) => {
+        if (code === 0) {
+          console.log('✅ YouTrack MCP server exited successfully');
+          resolve();
+        } else {
+          console.error(`❌ YouTrack MCP server exited with code ${code}`);
+          reject(new Error(`Server exited with code ${code}`));
+        }
+      });
+
+      // Handle graceful shutdown
+      process.on('SIGINT', () => {
+        console.log('\n🛑 Shutting down YouTrack MCP server...');
+        child.kill('SIGINT');
+      });
+
+      process.on('SIGTERM', () => {
+        console.log('\n🛑 Terminating YouTrack MCP server...');
+        child.kill('SIGTERM');
+      });
+    });
+  }
+
+  validateEnvironment() {
+    const requiredVars = ['YOUTRACK_URL', 'YOUTRACK_API_TOKEN'];
+    const missingVars = requiredVars.filter(varName => !process.env[varName]);
+    
+    if (missingVars.length > 0) {
+      console.warn('⚠️  Warning: Missing environment variables:', missingVars.join(', '));
+      console.warn('   The server may not function properly without these variables.');
+      console.warn('   Please set them in your environment or .env file.');
+    } else {
+      console.log('✅ Environment variables validated');
+    }
+  }
+
+  /**
+   * Get server information
+   */
+  getInfo() {
+    return {
+      name: 'YouTrack MCP Server',
+      version: '1.11.1',
+      description: 'A Model Context Protocol server for JetBrains YouTrack',
+      pythonPath: this.pythonPath,
+      serverPath: this.serverPath,
+      homepage: 'https://github.com/windbit/agentek-youtrack-mcp'
+    };
+  }
+}
+
+export default YouTrackMCPServer;