mcp-ticketer 0.4.2__tar.gz → 0.4.3__tar.gz

{mcp_ticketer-0.4.2 → mcp_ticketer-0.4.3}/.env.example

@@ -14,10 +14,17 @@
 # Get your API key from: https://linear.app/settings/api
 LINEAR_API_KEY=lin_api_YOUR_KEY_HERE
 
-# Your Linear team ID (recommended for auto-discovery)
-# Find it in: Settings → Teams → Your Team
-# Or from the URL when viewing your team: linear.app/YOUR-TEAM-ID/...
-LINEAR_TEAM_ID=YOUR-TEAM-ID
+# Linear Team Identification - Choose ONE of the following:
+# Option 1: Team key (recommended - short code like 'ENG', 'DESIGN', 'PRODUCT')
+LINEAR_TEAM_KEY=ENG
+
+# Option 2: Team UUID (for advanced use cases)
+# LINEAR_TEAM_ID=02d15669-7351-4451-9719-807576c16049
+
+# How to find your team key:
+# 1. Go to Linear Settings → Teams
+# 2. Select your team
+# 3. Look for the "Key" field (e.g., "ENG")
 
 # Optional: Linear project ID
 # LINEAR_PROJECT_ID=YOUR-PROJECT-ID

{mcp_ticketer-0.4.2 → mcp_ticketer-0.4.3}/CHANGELOG.md

@@ -4,7 +4,78 @@ All notable changes to MCP Ticketer will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.3] - 2025-10-27
+
+### Added
+- **LINEAR_TEAM_KEY Environment Variable**: Easier Linear configuration with team keys
+  - Added `LINEAR_TEAM_KEY` support as primary configuration option
+  - Team key (e.g., "ENG", "DESIGN") now recommended over team ID (UUID)
+  - Automatic resolution of team key to team ID in Linear adapter
+  - Updated `.env.example` with LINEAR_TEAM_KEY as default option
+  - CLI `init` command now prompts for team key by default
+- **Command Synonyms**: Init, install, and setup commands are now fully synonymous
+  - `mcp-ticketer init` - Initialize configuration
+  - `mcp-ticketer install` - Install and configure (same as init)
+  - `mcp-ticketer setup` - Setup (same as init)
+  - All three commands accept identical parameters and behave identically
+- **Attachment Model**: Universal file attachment support
+  - New `Attachment` model in core models for cross-adapter attachment representation
+  - Fields: id, ticket_id, filename, url, content_type, size_bytes, created_at, created_by, description, metadata
+  - Full documentation in new `docs/ATTACHMENTS.md` guide
+- **AITrackdown Attachment Support**: Complete file attachment implementation
+  - `add_attachment()` - Upload files to local filesystem with security features
+  - `get_attachments()` - List all attachments for a ticket
+  - `delete_attachment()` - Remove specific attachments
+  - Local filesystem storage in `.aitrackdown/attachments/<ticket-id>/` directories
+  - Automatic filename sanitization to prevent security issues
+  - SHA256 checksumming for file integrity verification
+  - MIME type detection based on file extension
+  - Size validation with configurable limits (default 100MB)
+  - Organized per-ticket storage structure
+- **MCP Attachment Tools**: AI agent attachment support with fallback
+  - `ticket_attach` - Add file attachments via MCP
+  - `ticket_attachments` - List attachments via MCP
+  - `ticket_delete_attachment` - Delete attachments via MCP
+  - Automatic fallback to comments for adapters without attachment support
+  - Graceful degradation for Linear, Jira, and GitHub adapters
+
+### Changed
+- **Linear Configuration**: LINEAR_TEAM_KEY is now the primary/recommended option
+  - Team ID (LINEAR_TEAM_ID) still supported for backward compatibility
+  - CLI init flow updated to prompt for team key first
+  - Documentation updated across README, QUICK_START, and setup guides
+- **Environment Variable Priority**: LINEAR_TEAM_KEY takes precedence over LINEAR_TEAM_ID
+  - When both are present, LINEAR_TEAM_KEY is used
+  - Adapter automatically resolves team key to team ID via GraphQL
+- **Documentation Structure**: New comprehensive attachment documentation
+  - Created `docs/ATTACHMENTS.md` (400+ lines)
+  - Updated README.md with attachment examples and LINEAR_TEAM_KEY info
+  - Updated QUICK_START.md with attachment usage and Linear team key setup
+  - Updated API_REFERENCE.md with complete Attachment model specification
+  - Added configuration section to README with Linear setup details
+
+### Fixed
+- **LINEAR_TEAM_KEY Environment Loading**: Proper loading from .env files
+  - Fixed `project_config.py` to check all LINEAR_* environment variables
+  - Environment variable discovery now detects LINEAR_TEAM_KEY
+  - Resolves issues where LINEAR_TEAM_KEY wasn't being recognized
+
+### Documentation
+- **New Files**:
+  - `docs/ATTACHMENTS.md` - Comprehensive attachment guide with examples, security notes, and roadmap
+- **Updated Files**:
+  - `README.md` - Added attachment features, LINEAR_TEAM_KEY configuration, and command synonyms
+  - `docs/QUICK_START.md` - Added attachment examples and LINEAR_TEAM_KEY setup instructions
+  - `docs/API_REFERENCE.md` - Added Attachment model specification and adapter methods
+  - `.env.example` - Updated with LINEAR_TEAM_KEY as primary option with clear instructions
+
+### Security
+- **Attachment Security Features**:
+  - Filename sanitization prevents path traversal and injection attacks
+  - Path resolution validates files stay within allowed directories
+  - File size limits prevent disk exhaustion
+  - SHA256 checksums enable integrity verification
+  - Isolated per-ticket storage prevents cross-ticket access
 
 ## [0.3.6] - 2025-01-25
 

{mcp_ticketer-0.4.2 → mcp_ticketer-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.4.2
+Version: 0.4.3
 Summary: Universal ticket management interface for AI agents with MCP support
 Author-email: MCP Ticketer Team <support@mcp-ticketer.io>
 Maintainer-email: MCP Ticketer Team <support@mcp-ticketer.io>
@@ -30,7 +30,7 @@ Classifier: Topic :: Software Development :: Bug Tracking
 Classifier: Topic :: System :: Monitoring
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: gql[httpx]>=3.0.0
@@ -104,6 +104,7 @@ Universal ticket management interface for AI agents with MCP (Model Context Prot
 - **🎨 Rich CLI**: Beautiful terminal interface with colors and tables
 - **📊 State Machine**: Built-in state transitions with validation
 - **🔍 Advanced Search**: Full-text search with multiple filters
+- **📎 File Attachments**: Upload, list, and manage ticket attachments (AITrackdown adapter)
 - **📦 Easy Installation**: Available on PyPI with simple pip install
 
 ## 📦 Installation
@@ -183,6 +184,10 @@ mcp-ticketer install
 mcp-ticketer init --adapter aitrackdown
 
 # For Linear (requires API key)
+# Option 1: Using team key (recommended)
+mcp-ticketer init --adapter linear --team-key ENG
+
+# Option 2: Using team ID
 mcp-ticketer init --adapter linear --team-id YOUR_TEAM_ID
 
 # For JIRA (requires server and credentials)
@@ -194,6 +199,11 @@ mcp-ticketer init --adapter jira \
 mcp-ticketer init --adapter github --repo owner/repo
 ```
 
+**Note:** The following commands are synonymous and can be used interchangeably:
+- `mcp-ticketer init` - Initialize configuration
+- `mcp-ticketer install` - Install and configure (same as init)
+- `mcp-ticketer setup` - Setup (same as init)
+
 ### 2. Create Your First Ticket
 
 ```bash
@@ -222,6 +232,24 @@ mcp-ticketer transition TICKET-123 in_progress
 mcp-ticketer search "login bug" --state open
 ```
 
+### 4. Working with Attachments (AITrackdown)
+
+```bash
+# Add attachment via MCP tools
+mcp-ticketer mcp call ticket_attach '{
+  "ticket_id": "task-123",
+  "file_path": "/path/to/document.pdf",
+  "description": "Project specification"
+}'
+
+# List attachments
+mcp-ticketer mcp call ticket_attachments '{
+  "ticket_id": "task-123"
+}'
+```
+
+For programmatic access, see the [Attachments Guide](docs/ATTACHMENTS.md).
+
 ## 🤖 MCP Server Integration
 
 MCP Ticketer provides seamless integration with AI clients through automatic configuration:
@@ -266,6 +294,37 @@ mcp-ticketer uninstall auggie        # Alias for remove
 
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for client-specific details.**
 
+## ⚙️ Configuration
+
+### Linear Configuration
+
+Configure Linear using either a team **key** (recommended) or team **ID**:
+
+**Option 1: Team Key** (Recommended)
+```bash
+# In .env or environment
+LINEAR_API_KEY=lin_api_...
+LINEAR_TEAM_KEY=ENG
+```
+
+**Option 2: Team ID**
+```bash
+# In .env or environment
+LINEAR_API_KEY=lin_api_...
+LINEAR_TEAM_ID=02d15669-7351-4451-9719-807576c16049
+```
+
+**Finding your team key in Linear:**
+1. Go to Linear Settings → Teams
+2. Select your team
+3. Look for the "Key" field (e.g., "ENG", "DESIGN", "PRODUCT")
+
+The team key is a short, human-readable identifier that's easier to use than the UUID-based team ID.
+
+### Environment Variables
+
+See [.env.example](.env.example) for a complete list of supported environment variables for all adapters.
+
 ## 📚 Documentation
 
 Full documentation is available at [https://mcp-ticketerer.readthedocs.io](https://mcp-ticketerer.readthedocs.io)

{mcp_ticketer-0.4.2 → mcp_ticketer-0.4.3}/README.md

@@ -19,6 +19,7 @@ Universal ticket management interface for AI agents with MCP (Model Context Prot
 - **🎨 Rich CLI**: Beautiful terminal interface with colors and tables
 - **📊 State Machine**: Built-in state transitions with validation
 - **🔍 Advanced Search**: Full-text search with multiple filters
+- **📎 File Attachments**: Upload, list, and manage ticket attachments (AITrackdown adapter)
 - **📦 Easy Installation**: Available on PyPI with simple pip install
 
 ## 📦 Installation
@@ -98,6 +99,10 @@ mcp-ticketer install
 mcp-ticketer init --adapter aitrackdown
 
 # For Linear (requires API key)
+# Option 1: Using team key (recommended)
+mcp-ticketer init --adapter linear --team-key ENG
+
+# Option 2: Using team ID
 mcp-ticketer init --adapter linear --team-id YOUR_TEAM_ID
 
 # For JIRA (requires server and credentials)
@@ -109,6 +114,11 @@ mcp-ticketer init --adapter jira \
 mcp-ticketer init --adapter github --repo owner/repo
 ```
 
+**Note:** The following commands are synonymous and can be used interchangeably:
+- `mcp-ticketer init` - Initialize configuration
+- `mcp-ticketer install` - Install and configure (same as init)
+- `mcp-ticketer setup` - Setup (same as init)
+
 ### 2. Create Your First Ticket
 
 ```bash
@@ -137,6 +147,24 @@ mcp-ticketer transition TICKET-123 in_progress
 mcp-ticketer search "login bug" --state open
 ```
 
+### 4. Working with Attachments (AITrackdown)
+
+```bash
+# Add attachment via MCP tools
+mcp-ticketer mcp call ticket_attach '{
+  "ticket_id": "task-123",
+  "file_path": "/path/to/document.pdf",
+  "description": "Project specification"
+}'
+
+# List attachments
+mcp-ticketer mcp call ticket_attachments '{
+  "ticket_id": "task-123"
+}'
+```
+
+For programmatic access, see the [Attachments Guide](docs/ATTACHMENTS.md).
+
 ## 🤖 MCP Server Integration
 
 MCP Ticketer provides seamless integration with AI clients through automatic configuration:
@@ -181,6 +209,37 @@ mcp-ticketer uninstall auggie        # Alias for remove
 
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for client-specific details.**
 
+## ⚙️ Configuration
+
+### Linear Configuration
+
+Configure Linear using either a team **key** (recommended) or team **ID**:
+
+**Option 1: Team Key** (Recommended)
+```bash
+# In .env or environment
+LINEAR_API_KEY=lin_api_...
+LINEAR_TEAM_KEY=ENG
+```
+
+**Option 2: Team ID**
+```bash
+# In .env or environment
+LINEAR_API_KEY=lin_api_...
+LINEAR_TEAM_ID=02d15669-7351-4451-9719-807576c16049
+```
+
+**Finding your team key in Linear:**
+1. Go to Linear Settings → Teams
+2. Select your team
+3. Look for the "Key" field (e.g., "ENG", "DESIGN", "PRODUCT")
+
+The team key is a short, human-readable identifier that's easier to use than the UUID-based team ID.
+
+### Environment Variables
+
+See [.env.example](.env.example) for a complete list of supported environment variables for all adapters.
+
 ## 📚 Documentation
 
 Full documentation is available at [https://mcp-ticketerer.readthedocs.io](https://mcp-ticketerer.readthedocs.io)

{mcp_ticketer-0.4.2 → mcp_ticketer-0.4.3}/docs/API_REFERENCE.md

@@ -166,6 +166,71 @@ comment = Comment(
 )
 ```
 
+### Attachment
+
+File attachments associated with tickets.
+
+```python
+class Attachment(BaseModel):
+    """File attachment metadata for tickets."""
+
+    id: Optional[str] = None
+    ticket_id: str
+    filename: str
+    url: Optional[str] = None
+    content_type: Optional[str] = None
+    size_bytes: Optional[int] = None
+    created_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    description: Optional[str] = None
+    metadata: Dict[str, Any] = {}
+```
+
+**Fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | `Optional[str]` | `None` | Attachment unique identifier |
+| `ticket_id` | `str` | *Required* | Parent ticket identifier |
+| `filename` | `str` | *Required* | Original filename |
+| `url` | `Optional[str]` | `None` | Download URL or file:// path |
+| `content_type` | `Optional[str]` | `None` | MIME type (e.g., 'application/pdf') |
+| `size_bytes` | `Optional[int]` | `None` | File size in bytes |
+| `created_at` | `Optional[datetime]` | `None` | Upload timestamp |
+| `created_by` | `Optional[str]` | `None` | User who uploaded the attachment |
+| `description` | `Optional[str]` | `None` | Attachment description or notes |
+| `metadata` | `Dict[str, Any]` | `{}` | Adapter-specific attachment metadata |
+
+**Example:**
+```python
+from datetime import datetime
+
+attachment = Attachment(
+    id='20250127143000-document.pdf',
+    ticket_id='task-123',
+    filename='document.pdf',
+    url='file:///project/.aitrackdown/attachments/task-123/document.pdf',
+    content_type='application/pdf',
+    size_bytes=1048576,
+    created_at=datetime.now(),
+    created_by='user@example.com',
+    description='Project specification document',
+    metadata={
+        'checksum': 'a3c7f8d2e1b4c5f6...',
+        'sanitized_filename': 'document.pdf'
+    }
+)
+```
+
+**Adapter Support:**
+
+| Adapter | Support | Notes |
+|---------|---------|-------|
+| AITrackdown | ✅ Full | Local filesystem storage with security features |
+| Jira | ❌ Planned | REST API v3 integration coming soon |
+| Linear | ❌ Planned | GraphQL mutation support coming soon |
+| GitHub | ❌ Not supported | GitHub Issues doesn't support direct attachments |
+
 ### SearchQuery
 
 Query parameters for searching tickets.
@@ -364,6 +429,44 @@ class BaseAdapter(ABC, Generic[T]):
         """Get comments for a ticket."""
         pass
 
+    # Attachment Operations
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: Optional[str] = None
+    ) -> Attachment:
+        """Add a file attachment to a ticket.
+
+        Default implementation raises NotImplementedError.
+        Adapters should override to provide attachment support.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support attachments"
+        )
+
+    async def get_attachments(self, ticket_id: str) -> List[Attachment]:
+        """Get all attachments for a ticket.
+
+        Default implementation returns empty list.
+        Adapters should override to provide attachment support.
+        """
+        return []
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str
+    ) -> bool:
+        """Delete a specific attachment.
+
+        Default implementation raises NotImplementedError.
+        Adapters should override to provide attachment support.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support attachment deletion"
+        )
+
     # State Mapping Utilities
     def map_state_to_system(self, state: TicketState) -> str:
         """Map universal state to system-specific state."""