agentek-youtrack-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Anton Zorin
+Copyright (c) 2026 Agentek
+
+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,332 @@
+# YouTrack MCP
+
+A Model Context Protocol (MCP) server that provides access to YouTrack functionality.
+
+## 🚀 Quick Reference - Common Operations
+
+### **🎯 State Transitions (Most Common)**
+```python
+# ✅ PROVEN WORKING FORMAT - Use simple strings
+update_issue_state("DEMO-123", "In Progress")
+update_issue_state("PROJECT-456", "Fixed")
+update_issue_state("TASK-789", "Closed")
+
+# ❌ DON'T USE - Complex objects fail
+# update_custom_fields(issue_id, {"State": {"name": "In Progress"}})  # FAILS
+# update_custom_fields(issue_id, {"State": {"id": "154-2"}})         # FAILS
+```
+
+### **🚨 Priority Updates (Very Common)**
+```python
+# ✅ PROVEN WORKING FORMAT - Use simple strings
+update_issue_priority("DEMO-123", "Critical")
+update_issue_priority("PROJECT-456", "Major") 
+update_issue_priority("TASK-789", "Normal")
+
+# ❌ DON'T USE - Complex objects fail
+# update_custom_fields(issue_id, {"Priority": {"name": "Critical"}})  # FAILS
+# update_custom_fields(issue_id, {"Priority": {"id": "152-1"}})       # FAILS
+```
+
+### **👤 Assignment Updates (Common)**
+```python
+# ✅ PROVEN WORKING FORMAT - Use login names
+update_issue_assignee("DEMO-123", "admin")
+update_issue_assignee("PROJECT-456", "john.doe")
+update_issue_assignee("TASK-789", "jane.smith")
+
+# ❌ DON'T USE - Complex objects fail
+# update_custom_fields(issue_id, {"Assignee": {"login": "admin"}})    # FAILS
+```
+
+### **🏷️ Type Updates (Common)**
+```python
+# ✅ PROVEN WORKING FORMAT - Use simple strings
+update_issue_type("DEMO-123", "Bug")
+update_issue_type("PROJECT-456", "Feature")
+update_issue_type("TASK-789", "Task")
+
+# ❌ DON'T USE - Complex objects fail
+# update_custom_fields(issue_id, {"Type": {"name": "Bug"}})          # FAILS
+```
+
+### **⏱️ Time Estimation (Common)**
+```python
+# ✅ PROVEN WORKING FORMAT - Use simple time strings
+update_issue_estimation("DEMO-123", "4h")     # 4 hours
+update_issue_estimation("PROJECT-456", "2d")  # 2 days
+update_issue_estimation("TASK-789", "30m")    # 30 minutes
+update_issue_estimation("TASK-790", "1w")     # 1 week
+update_issue_estimation("TASK-791", "3d 5h")  # 3 days 5 hours
+
+# ❌ DON'T USE - ISO duration or complex formats fail
+# update_custom_fields(issue_id, {"Estimation": "PT4H"})             # FAILS
+```
+
+### **⚡ Complete Issue Workflows**
+```python
+# 🎯 Complete Triage Workflow
+update_issue_type("DEMO-123", "Bug")           # Classify as bug
+update_issue_priority("DEMO-123", "Critical")  # Set priority  
+update_issue_assignee("DEMO-123", "admin")     # Assign to admin
+update_issue_estimation("DEMO-123", "4h")      # Estimate 4 hours
+update_issue_state("DEMO-123", "In Progress")  # Start work
+add_comment("DEMO-123", "Critical bug triaged and assigned")
+
+# 🚀 Feature Development Workflow  
+update_issue_type("PROJ-456", "Feature")       # Classify as feature
+update_issue_priority("PROJ-456", "Normal")    # Standard priority
+update_issue_assignee("PROJ-456", "jane.doe")  # Assign to developer
+update_issue_estimation("PROJ-456", "2d")      # Estimate 2 days
+add_comment("PROJ-456", "Feature ready for development")
+
+# ✅ Task Completion Workflow
+update_issue_state("TASK-789", "Fixed")        # Mark as fixed
+add_comment("TASK-789", "Implementation completed and tested")
+
+# 📊 Quick Updates (Most Common)
+update_issue_state("DEMO-123", "In Progress")       # Start work
+update_issue_priority("DEMO-123", "Critical")       # Escalate
+update_issue_assignee("DEMO-123", "admin")          # Reassign
+update_issue_type("DEMO-123", "Bug")                # Reclassify
+update_issue_estimation("DEMO-123", "6h")           # Re-estimate
+```
+
+### **📝 Other Custom Fields**
+```python
+# ✅ Working formats for different field types:
+
+# Priority (enum field)
+update_custom_fields("DEMO-123", {"Priority": "Critical"})
+
+# Assignee (user field) 
+update_custom_fields("DEMO-123", {"Assignee": "admin"})
+
+# Estimation (period field)
+update_custom_fields("DEMO-123", {"Estimation": "4h"})
+
+# Type (enum field)
+update_custom_fields("DEMO-123", {"Type": "Bug"})
+
+# Multiple fields at once
+update_custom_fields("DEMO-123", {
+    "Priority": "Critical",
+    "Assignee": "admin", 
+    "Type": "Bug"
+})
+```
+
+### **🔍 Finding Issues**
+```python
+# Search by text
+search_issues("bug in login")
+
+# Search by project
+get_project_issues("DEMO")
+
+# Get specific issue
+get_issue("DEMO-123")
+```
+
+### **📋 Creating Issues**
+```python
+create_issue(
+    project_id="DEMO",
+    summary="Bug in login system",
+    description="Users cannot log in with special characters"
+)
+```
+
+### **🔗 Linking Issues**
+```python
+# Create dependency
+add_dependency("DEMO-123", "DEMO-124")
+
+# Create relates link
+add_relates_link("DEMO-123", "DEMO-125")
+```
+
+### **💬 Comments**
+```python
+add_comment("DEMO-123", "Fixed the login bug")
+get_issue_comments("DEMO-123")
+```
+
+### **📎 Attachments**
+```python
+# Get raw issue data with attachments
+get_issue_raw("DEMO-123")
+
+# Download attachment content as base64
+get_attachment_content("DEMO-123", "1-456")
+
+# Delete an attachment (requires permissions)
+delete_attachment("DEMO-123", "1-456")
+```
+
+---
+
+## Installation
+
+[![Docker Build and Push](https://github.com/windbit/agentek-youtrack-mcp/actions/workflows/docker-build.yml/badge.svg)](https://github.com/windbit/agentek-youtrack-mcp/actions/workflows/docker-build.yml)
+
+This project provides a Model Context Protocol (MCP) server for YouTrack, enabling seamless integration with Claude Desktop and other MCP clients.
+
+## Quick Start
+
+### Using Docker (Recommended)
+
+Choose from multiple registries:
+
+#### Docker Hub (Primary)
+```bash
+# Use the latest stable release
+docker run --rm \
+  -e YOUTRACK_URL="https://your-instance.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-instance.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  windbit/agentek-youtrack-mcp:1.1.2_wip
+```
+
+#### GitHub Container Registry (New)
+```bash
+# Use the latest stable release
+docker run --rm \
+  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  ghcr.io/windbit/agentek-youtrack-mcp:latest
+
+# Or use the latest development build
+docker run --rm \
+  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
+  -e YOUTRACK_API_TOKEN="your-token" \
+  ghcr.io/windbit/agentek-youtrack-mcp:1.1.2_wip
+```
+
+### Available Docker Tags
+
+Both registries provide identical tags:
+
+- `latest` - Latest stable release (currently 1.1.2)
+- `1.1.2` - Specific version tags  
+- `1.1.2_wip` - Work-in-progress builds from main branch
+- `pr-<number>` - Pull request builds for testing
+
+*Note: Images are now published to both Docker Hub and GitHub Container Registry simultaneously.*
+
+### Using npm Package
+
+Choose from multiple registries:
+
+#### npmjs.org (Primary)
+```bash
+# Install globally
+npm install -g agentek-youtrack-mcp
+
+# Or use with npx (no installation required)
+npx agentek-youtrack-mcp
+```
+
+#### GitHub Packages (New)
+```bash
+# Configure GitHub registry
+npm config set @windbit:registry https://npm.pkg.github.com
+
+# Install globally
+npm install -g @windbit/agentek-youtrack-mcp
+
+# Or use with npx
+npx @windbit/agentek-youtrack-mcp
+```
+
+## 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
+- **Comprehensive API**: Full YouTrack REST API integration
+
+## Development
+
+This project maintains high code quality with comprehensive testing:
+
+- **Test Coverage**: 41% (continuously improving)
+- **CI/CD Pipeline**: Automated testing and Docker builds
+- **Quality Assurance**: Automated testing on every commit
+
+For development instructions, see the [Automation Scripts Guide](automations/README.md) and [Release Process](automations/RELEASE_INSTRUCTIONS.md).
+
+## Configuration
+
+### Environment Variables
+
+- `YOUTRACK_URL`: Your YouTrack instance URL
+- `YOUTRACK_API_TOKEN`: Your YouTrack API token
+- `YOUTRACK_VERIFY_SSL`: SSL verification (default: true)
+- `DISABLED_TOOLS`: Comma-separated list of tools to disable (denylist mode)
+- `ENABLED_TOOLS`: Comma-separated list of tools to enable (allowlist mode)
+
+### Tool Filtering
+
+You can reduce context pollution and token usage by filtering which tools are available:
+
+**Denylist Mode** - Disable specific tools:
+```bash
+export DISABLED_TOOLS="create_issue,update_issue,delete_page"
+```
+
+**Allowlist Mode** - Enable only specific tools (disables all others):
+```bash
+export ENABLED_TOOLS="get_issue,search_issues,get_projects"
+```
+
+**Notes:**
+- Tool names are case-insensitive (`Get_Issue` = `get_issue`)
+- Hyphens and underscores are equivalent (`get-issue` = `get_issue`)
+- If `ENABLED_TOOLS` is set, it takes precedence over `DISABLED_TOOLS`
+- Invalid tool names generate warnings but don't cause errors
+- Filtering happens at startup for maximum efficiency
+
+### Example Configuration
+
+```bash
+export YOUTRACK_URL="https://prodcamp.youtrack.cloud/"
+export YOUTRACK_API_TOKEN="perm-YWRtaW4=.NDMtMg==.JgbpvnDbEu7RSWwAJT6Ab3iXgQyPwu"
+export YOUTRACK_VERIFY_SSL="true"
+```
+
+## Documentation
+
+- [Development Workflow & Release Process](automations/RELEASE_INSTRUCTIONS.md)
+- [Docker Tagging Strategy](automations/DOCKER_TAGGING.md)
+- [Testing Guide](tests/README.md)
+- [Automation Scripts](automations/README.md)
+
+## Support
+
+For issues and questions:
+1. Check the [Issues](https://github.com/windbit/agentek-youtrack-mcp/issues) page
+2. Review the documentation
+3. Submit a new issue with detailed information
+
+---
+
+*Latest update: Comprehensive custom fields management with 567 test coverage and clean project organization.*
+
+## Version 1.11.1 Released
+
+🎉 **MAJOR FEATURE** - Custom Fields Management Support
+- ✅ Complete custom fields CRUD operations (create, read, update, delete)
+- ✅ Field validation against project schema (all field types supported)
+- ✅ Batch update capabilities for performance
+- ✅ Comprehensive error handling with detailed messages
+- ✅ 567 tests (+68 new tests) with extensive coverage
+- ✅ Clean project organization with `automations/` directory