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

{mcp_ticketer-0.4.1 → 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.1 → 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.1 → mcp_ticketer-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.4.1
+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,11 +30,12 @@ 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
 Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.2.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -65,7 +66,7 @@ Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == "docs"
 Requires-Dist: sphinx-click>=5.1.0; extra == "docs"
 Requires-Dist: myst-parser>=2.0.0; extra == "docs"
 Provides-Extra: mcp
-Requires-Dist: mcp>=0.1.0; extra == "mcp"
+Requires-Dist: mcp>=1.2.0; extra == "mcp"
 Provides-Extra: jira
 Requires-Dist: jira>=3.5.0; extra == "jira"
 Requires-Dist: ai-trackdown-pytools>=1.5.0; extra == "jira"
@@ -103,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
@@ -138,29 +140,37 @@ MCP Ticketer integrates with multiple AI clients via the Model Context Protocol
 
 | AI Client | Support | Config Type | Project-Level | Setup Command |
 |-----------|---------|-------------|---------------|---------------|
-| **Claude Code** | ✅ Native | JSON | ✅ Yes | `mcp-ticketer mcp claude` |
-| **Gemini CLI** | ✅ Full | JSON | ✅ Yes | `mcp-ticketer mcp gemini` |
-| **Codex CLI** | ✅ Full | TOML | ❌ Global only | `mcp-ticketer mcp codex` |
-| **Auggie** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer mcp auggie` |
+| **Claude Code** | ✅ Native | JSON | ✅ Yes | `mcp-ticketer install claude-code` |
+| **Claude Desktop** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer install claude-desktop` |
+| **Gemini CLI** | ✅ Full | JSON | ✅ Yes | `mcp-ticketer install gemini` |
+| **Codex CLI** | ✅ Full | TOML | ❌ Global only | `mcp-ticketer install codex` |
+| **Auggie** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer install auggie` |
 
 ### Quick MCP Setup
 
 ```bash
 # Claude Code (recommended for project-specific workflows)
-mcp-ticketer init --adapter aitrackdown  # First, initialize an adapter
-mcp-ticketer mcp claude                   # Then configure MCP
+mcp-ticketer init --adapter aitrackdown    # First, initialize an adapter
+mcp-ticketer install claude-code           # Then install MCP configuration
+
+# Claude Desktop (global configuration)
+mcp-ticketer init --adapter aitrackdown
+mcp-ticketer install claude-desktop
 
 # Gemini CLI (Google's AI client)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp gemini --scope project
+mcp-ticketer install gemini
 
 # Codex CLI (global configuration, requires restart)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp codex
+mcp-ticketer install codex
 
 # Auggie (simple global setup)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp auggie
+mcp-ticketer install auggie
+
+# Show available platforms
+mcp-ticketer install
 ```
 
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for detailed setup instructions.**
@@ -174,6 +184,10 @@ mcp-ticketer mcp auggie
 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)
@@ -185,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
@@ -213,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:
@@ -221,11 +258,16 @@ MCP Ticketer provides seamless integration with AI clients through automatic con
 # Run MCP server manually (for testing)
 mcp-ticketer serve
 
-# Or configure your AI client automatically (recommended)
-mcp-ticketer mcp claude  # For Claude Code
-mcp-ticketer mcp gemini  # For Gemini CLI
-mcp-ticketer mcp codex   # For Codex CLI
-mcp-ticketer mcp auggie  # For Auggie
+# Or install MCP configuration automatically (recommended)
+mcp-ticketer install claude-code     # For Claude Code (project-level)
+mcp-ticketer install claude-desktop  # For Claude Desktop (global)
+mcp-ticketer install gemini          # For Gemini CLI
+mcp-ticketer install codex           # For Codex CLI
+mcp-ticketer install auggie          # For Auggie
+
+# Remove MCP configuration when needed
+mcp-ticketer remove claude-code      # Remove from Claude Code
+mcp-ticketer uninstall auggie        # Alias for remove
 ```
 
 **Configuration is automatic** - the commands above will:
@@ -252,6 +294,37 @@ mcp-ticketer mcp auggie  # For Auggie
 
 **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.1 → 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
@@ -54,29 +55,37 @@ MCP Ticketer integrates with multiple AI clients via the Model Context Protocol
 
 | AI Client | Support | Config Type | Project-Level | Setup Command |
 |-----------|---------|-------------|---------------|---------------|
-| **Claude Code** | ✅ Native | JSON | ✅ Yes | `mcp-ticketer mcp claude` |
-| **Gemini CLI** | ✅ Full | JSON | ✅ Yes | `mcp-ticketer mcp gemini` |
-| **Codex CLI** | ✅ Full | TOML | ❌ Global only | `mcp-ticketer mcp codex` |
-| **Auggie** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer mcp auggie` |
+| **Claude Code** | ✅ Native | JSON | ✅ Yes | `mcp-ticketer install claude-code` |
+| **Claude Desktop** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer install claude-desktop` |
+| **Gemini CLI** | ✅ Full | JSON | ✅ Yes | `mcp-ticketer install gemini` |
+| **Codex CLI** | ✅ Full | TOML | ❌ Global only | `mcp-ticketer install codex` |
+| **Auggie** | ✅ Full | JSON | ❌ Global only | `mcp-ticketer install auggie` |
 
 ### Quick MCP Setup
 
 ```bash
 # Claude Code (recommended for project-specific workflows)
-mcp-ticketer init --adapter aitrackdown  # First, initialize an adapter
-mcp-ticketer mcp claude                   # Then configure MCP
+mcp-ticketer init --adapter aitrackdown    # First, initialize an adapter
+mcp-ticketer install claude-code           # Then install MCP configuration
+
+# Claude Desktop (global configuration)
+mcp-ticketer init --adapter aitrackdown
+mcp-ticketer install claude-desktop
 
 # Gemini CLI (Google's AI client)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp gemini --scope project
+mcp-ticketer install gemini
 
 # Codex CLI (global configuration, requires restart)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp codex
+mcp-ticketer install codex
 
 # Auggie (simple global setup)
 mcp-ticketer init --adapter aitrackdown
-mcp-ticketer mcp auggie
+mcp-ticketer install auggie
+
+# Show available platforms
+mcp-ticketer install
 ```
 
 **See [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for detailed setup instructions.**
@@ -90,6 +99,10 @@ mcp-ticketer mcp auggie
 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)
@@ -101,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
@@ -129,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:
@@ -137,11 +173,16 @@ MCP Ticketer provides seamless integration with AI clients through automatic con
 # Run MCP server manually (for testing)
 mcp-ticketer serve
 
-# Or configure your AI client automatically (recommended)
-mcp-ticketer mcp claude  # For Claude Code
-mcp-ticketer mcp gemini  # For Gemini CLI
-mcp-ticketer mcp codex   # For Codex CLI
-mcp-ticketer mcp auggie  # For Auggie
+# Or install MCP configuration automatically (recommended)
+mcp-ticketer install claude-code     # For Claude Code (project-level)
+mcp-ticketer install claude-desktop  # For Claude Desktop (global)
+mcp-ticketer install gemini          # For Gemini CLI
+mcp-ticketer install codex           # For Codex CLI
+mcp-ticketer install auggie          # For Auggie
+
+# Remove MCP configuration when needed
+mcp-ticketer remove claude-code      # Remove from Claude Code
+mcp-ticketer uninstall auggie        # Alias for remove
 ```
 
 **Configuration is automatic** - the commands above will:
@@ -168,6 +209,37 @@ mcp-ticketer mcp auggie  # For Auggie
 
 **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.1 → mcp_ticketer-0.4.3}/docs/AI_CLIENT_INTEGRATION.md

@@ -77,11 +77,12 @@ Before integrating with any AI client, ensure you have:
 pip install mcp-ticketer
 mcp-ticketer init --adapter aitrackdown
 
-# 2. Configure your AI client (choose ONE)
-mcp-ticketer mcp claude  # Claude Code (recommended)
-mcp-ticketer mcp gemini  # Gemini CLI
-mcp-ticketer mcp codex   # Codex CLI
-mcp-ticketer mcp auggie  # Auggie
+# 2. Install MCP configuration for your AI client (choose ONE)
+mcp-ticketer install claude-code     # Claude Code (project-level, recommended)
+mcp-ticketer install claude-desktop  # Claude Desktop (global)
+mcp-ticketer install gemini          # Gemini CLI
+mcp-ticketer install codex           # Codex CLI
+mcp-ticketer install auggie          # Auggie
 ```
 
 ---
@@ -135,14 +136,14 @@ mcp-ticketer init --adapter github --repo owner/repo
 #### Step 3: Configure MCP Integration
 
 ```bash
-# Project-level configuration (recommended)
-mcp-ticketer mcp claude
+# Project-level configuration (recommended for Claude Code)
+mcp-ticketer install claude-code
 
-# Global configuration (Claude Desktop)
-mcp-ticketer mcp claude --global
+# Global configuration (for Claude Desktop)
+mcp-ticketer install claude-desktop
 
-# Force overwrite existing configuration
-mcp-ticketer mcp claude --force
+# Preview changes without applying them
+mcp-ticketer install claude-code --dry-run
 ```
 
 #### Step 4: Verify Configuration
@@ -274,14 +275,11 @@ mcp-ticketer init --adapter aitrackdown
 #### Step 3: Configure MCP Integration
 
 ```bash
-# Project-level configuration (recommended)
-mcp-ticketer mcp gemini --scope project
+# Install Gemini CLI configuration (project-level by default)
+mcp-ticketer install gemini
 
-# User-level configuration (global)
-mcp-ticketer mcp gemini --scope user
-
-# Force overwrite
-mcp-ticketer mcp gemini --scope project --force
+# Preview changes without applying them
+mcp-ticketer install gemini --dry-run
 ```
 
 #### Step 4: Verify Configuration
@@ -399,11 +397,11 @@ mcp-ticketer init --adapter aitrackdown
 #### Step 3: Configure MCP Integration
 
 ```bash
-# Configure Codex (global-only)
-mcp-ticketer mcp codex
+# Install Codex CLI configuration (global-only)
+mcp-ticketer install codex
 
-# Force overwrite
-mcp-ticketer mcp codex --force
+# Preview changes without applying them
+mcp-ticketer install codex --dry-run
 ```
 
 ⚠️ **IMPORTANT:** Codex CLI does NOT support project-level configuration.
@@ -500,11 +498,11 @@ mcp-ticketer init --adapter aitrackdown
 #### Step 3: Configure MCP Integration
 
 ```bash
-# Configure Auggie (global-only)
-mcp-ticketer mcp auggie
+# Install Auggie configuration (global-only)
+mcp-ticketer install auggie
 
-# Force overwrite
-mcp-ticketer mcp auggie --force
+# Preview changes without applying them
+mcp-ticketer install auggie --dry-run
 ```
 
 #### Step 4: Restart Auggie
@@ -711,8 +709,9 @@ This ensures tickets are accessible across all projects when using Auggie.
 # Find the binary path
 which mcp-ticketer
 
-# Update config with absolute path
-mcp-ticketer mcp claude --force
+# Reinstall configuration
+mcp-ticketer remove claude-code
+mcp-ticketer install claude-code
 ```
 
 #### 2. "Adapter not configured"
@@ -753,8 +752,9 @@ cat .gemini/settings.json
 # Verify .gitignore
 cat .gitignore | grep .gemini
 
-# Reconfigure
-mcp-ticketer mcp gemini --scope project --force
+# Reinstall configuration
+mcp-ticketer remove gemini
+mcp-ticketer install gemini
 ```
 
 #### 5. "Server not responding" (Codex CLI)
@@ -817,8 +817,8 @@ python -c "import tomli; print(tomli.load(open('~/.codex/config.toml', 'rb')))"
 # 1. Your adapter config is already compatible
 # No changes needed to .mcp-ticketer/config.json
 
-# 2. Configure Gemini CLI
-mcp-ticketer mcp gemini --scope project
+# 2. Install Gemini CLI configuration
+mcp-ticketer install gemini
 
 # 3. Both clients can now use the same adapter
 # No data migration required
@@ -831,8 +831,8 @@ mcp-ticketer mcp gemini --scope project
 cd /path/to/project
 mcp-ticketer init --adapter aitrackdown
 
-# 2. Configure new client
-mcp-ticketer mcp claude  # or: mcp-ticketer mcp gemini
+# 2. Install configuration for new client
+mcp-ticketer install claude-code  # or: mcp-ticketer install gemini
 
 # 3. Migrate tickets (optional)
 # Copy tickets from global storage to project storage
@@ -846,8 +846,8 @@ cp -r ~/.mcp-ticketer/.aitrackdown/* .aitrackdown/
 mkdir -p ~/.mcp-ticketer
 cp .mcp-ticketer/config.json ~/.mcp-ticketer/
 
-# 2. Configure global client
-mcp-ticketer mcp codex  # or: mcp-ticketer mcp auggie
+# 2. Install configuration for global client
+mcp-ticketer install codex  # or: mcp-ticketer install auggie
 
 # 3. Update paths in global config
 # Edit ~/.codex/config.toml or ~/.augment/settings.json
@@ -888,7 +888,8 @@ MCP_TICKETER_ADAPTER = "aitrackdown"
 **Conversion script:**
 ```bash
 # Use mcp-ticketer's built-in conversion
-mcp-ticketer mcp codex --force
+mcp-ticketer remove codex
+mcp-ticketer install codex
 ```
 
 ---