mcp-ticketer 0.1.23__tar.gz → 0.1.26__tar.gz

{mcp_ticketer-0.1.23 → mcp_ticketer-0.1.26}/CHANGELOG.md

@@ -15,6 +15,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Analytics dashboard
 - Webhook notification support
 
+## [0.1.26] - 2025-10-23
+
+### Changed
+- Maintenance release with build and packaging improvements
+- Updated development dependencies and build process
+
+## [0.1.25] - 2025-10-23
+
+### Fixed
+- **Critical MCP Server Fix**: Fixed adapter registration issue where Linear and other adapters were not available in MCP server
+  - Added missing import of adapters module in MCP server initialization
+  - Resolves "Adapter 'linear' not registered" errors when using MCP clients (Auggie, Claude, etc.)
+  - All adapters (aitrackdown, linear, jira, github) now properly registered on server startup
+- **Auggie Integration**: Fixed MCP connection failures with Auggie CLI due to missing adapter registration
+
+## [0.1.24] - 2025-10-24
+
+### Added
+- **Multi-Client MCP Support**: Added support for 4 AI clients
+  - Claude Code integration with project and global config (`mcp-ticketer mcp claude`)
+  - Gemini CLI integration with project/user scope (`mcp-ticketer mcp gemini`)
+  - Codex CLI integration with global TOML config (`mcp-ticketer mcp codex`)
+  - Auggie CLI integration with global JSON config (`mcp-ticketer mcp auggie`)
+- **Nested Command Structure**: New `mcp` command group with 4 client-specific subcommands
+- **Configuration Modules**: Three new CLI configuration modules
+  - `auggie_configure.py` - Auggie CLI configuration handler
+  - `codex_configure.py` - Codex CLI TOML configuration handler
+  - `gemini_configure.py` - Gemini CLI JSON configuration handler
+- **TOML Support**: Added `tomli` and `tomli-w` dependencies for Codex CLI TOML config
+- **Comprehensive Documentation**:
+  - AI Client Integration Guide (docs/AI_CLIENT_INTEGRATION.md, 937 lines)
+  - Codex Integration Guide (CODEX_INTEGRATION.md, 312 lines)
+  - Updated CLAUDE.md with 800+ lines of multi-client documentation
+  - Updated README.md with AI client comparison table
+  - Updated QUICK_START.md with client selection decision tree
+
+### Changed
+- **Command Structure**: Renamed MCP commands to nested structure under `mcp` parent command
+  - `mcp-ticketer mcp` → `mcp-ticketer mcp claude`
+  - `mcp-ticketer gemini` → `mcp-ticketer mcp gemini`
+  - `mcp-ticketer codex` → `mcp-ticketer mcp codex`
+  - `mcp-ticketer auggie` → `mcp-ticketer mcp auggie`
+- **Documentation Version**: Updated CLAUDE.md from 0.1.11 to 0.1.24
+- **Type Hints**: Modernized type hints in JIRA and Linear adapters
+- **gitignore**: Added `.gemini/` directory exclusion
+
+### Fixed
+- Removed obsolete MCP server startup error documentation
+- Improved configuration file handling for multiple AI clients
+- Enhanced MCP server path detection and validation
+
 ## [0.1.10] - 2025-09-29
 
 ### Fixed

{mcp_ticketer-0.1.23 → mcp_ticketer-0.1.26}/CLAUDE.md

@@ -1,9 +1,9 @@
 # CLAUDE.md - MCP Ticketer AI Agent Instructions
 
-**Version**: 0.1.11
-**Last Updated**: 2025-10-22
+**Version**: 0.1.24
+**Last Updated**: 2025-10-24
 **Project**: MCP Ticketer - Universal Ticket Management Interface for AI Agents
-**Optimized For**: Claude Code, Claude MPM, and AI Agent Collaboration
+**Optimized For**: Claude Code, Gemini CLI, Codex CLI, Auggie, and AI Agent Collaboration
 
 ---
 
@@ -800,9 +800,45 @@ mcp-ticketer --help       # Show CLI help
 
 ---
 
-## ⚪ OPTIONAL: AI Agent Integration
+## ⚪ OPTIONAL: AI Client Integration
 
-### Claude Code Integration
+### Overview: Multiple AI Client Support
+
+**MCP Ticketer supports 4 major AI clients with MCP integration:**
+
+| Client | Project-Level | Config Format | Config Location | Command |
+|--------|---------------|---------------|-----------------|---------|
+| **Claude Code** | ✅ Yes | JSON | `.claude/mcp.json` | `mcp-ticketer mcp claude` |
+| **Gemini CLI** | ✅ Yes | JSON | `.gemini/settings.json` | `mcp-ticketer mcp gemini` |
+| **Codex CLI** | ❌ No (Global only) | TOML | `~/.codex/config.toml` | `mcp-ticketer mcp codex` |
+| **Auggie** | ❌ No (Global only) | JSON | `~/.augment/settings.json` | `mcp-ticketer mcp auggie` |
+
+**Quick Setup:**
+```bash
+# Claude Code (project-level, recommended)
+mcp-ticketer mcp claude
+
+# Gemini CLI (project-level)
+mcp-ticketer mcp gemini --scope project
+
+# Codex CLI (global-only, restart required)
+mcp-ticketer mcp codex
+
+# Auggie (global-only)
+mcp-ticketer mcp auggie
+```
+
+**When to use which client:**
+- **Claude Code**: Best for project-specific workflows, native MCP support
+- **Gemini CLI**: Google's AI client, supports project-level configuration
+- **Codex CLI**: Global configuration only, requires restart after config changes
+- **Auggie**: Simple global setup, suitable for single-project users
+
+**See Also:** [AI Client Integration Guide](docs/AI_CLIENT_INTEGRATION.md) for comprehensive setup instructions.
+
+---
+
+### Claude Code Integration (Recommended)
 
 **MCP Ticketer is optimized for Claude Code workflows:**
 
@@ -811,13 +847,31 @@ mcp-ticketer --help       # Show CLI help
 make install-dev
 make init-aitrackdown
 
-# 2. Enable MCP server for Claude Desktop
-# Add to Claude Desktop config:
+# 2. Configure MCP integration (THE ONLY WAY)
+mcp-ticketer mcp claude
+
+# Alternative: Configure for Claude Desktop (global)
+mcp-ticketer mcp claude --global
+
+# 3. Configuration created at:
+# Project-level: .claude/mcp.json
+# Global: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
+#         %APPDATA%/Claude/claude_desktop_config.json (Windows)
+#         ~/.config/Claude/claude_desktop_config.json (Linux)
+
+# 4. Use via Claude Code
+# Claude can now create, read, update tickets directly
+# Example: "Create a high-priority task for fixing the login bug"
+```
+
+**Example Configuration (.claude/mcp.json):**
+```json
 {
   "mcpServers": {
-    "ticketer": {
-      "command": "mcp-ticketer-server",
-      "args": [],
+    "mcp-ticketer": {
+      "command": "/path/to/mcp-ticketer",
+      "args": ["serve"],
+      "cwd": "/Users/masa/Projects/mcp-ticketer",
       "env": {
         "MCP_TICKETER_ADAPTER": "aitrackdown",
         "MCP_TICKETER_BASE_PATH": "/Users/masa/Projects/mcp-ticketer/.aitrackdown"
@@ -825,12 +879,181 @@ make init-aitrackdown
     }
   }
 }
+```
 
-# 3. Use via Claude Code
-# Claude can now create, read, update tickets directly
-# Example: "Create a high-priority task for fixing the login bug"
+---
+
+### Gemini CLI Integration
+
+**Google's Gemini CLI with project-level MCP support:**
+
+```bash
+# 1. Initialize mcp-ticketer
+make install-dev
+make init-aitrackdown
+
+# 2. Configure for Gemini CLI (THE ONLY WAY)
+mcp-ticketer mcp gemini --scope project
+
+# Alternative: Global configuration
+mcp-ticketer mcp gemini --scope user
+
+# 3. Configuration created at:
+# Project-level: .gemini/settings.json (added to .gitignore automatically)
+# User-level: ~/.gemini/settings.json
+
+# 4. Use with Gemini CLI
+# Run gemini command in project directory
+# MCP tools automatically available
+```
+
+**Example Configuration (.gemini/settings.json):**
+```json
+{
+  "mcpServers": {
+    "mcp-ticketer": {
+      "command": "/path/to/mcp-ticketer",
+      "args": ["serve"],
+      "env": {
+        "PYTHONPATH": "/path/to/project/src",
+        "MCP_TICKETER_ADAPTER": "aitrackdown",
+        "MCP_TICKETER_BASE_PATH": "/path/to/project/.aitrackdown"
+      },
+      "timeout": 15000,
+      "trust": false
+    }
+  }
+}
+```
+
+**Features:**
+- ✅ Project-level configuration support
+- ✅ JSON configuration format (familiar)
+- ✅ Automatic .gitignore management
+- ✅ 15-second timeout for MCP operations
+- ✅ Security: untrusted by default
+
+---
+
+### Codex CLI Integration
+
+**⚠️ IMPORTANT: Codex CLI only supports GLOBAL configuration**
+
+```bash
+# 1. Initialize mcp-ticketer
+make install-dev
+make init-aitrackdown
+
+# 2. Configure for Codex CLI (THE ONLY WAY)
+mcp-ticketer mcp codex
+
+# 3. Configuration created at:
+# Global only: ~/.codex/config.toml
+
+# 4. RESTART Codex CLI (REQUIRED)
+# Codex does not hot-reload configuration
+
+# 5. Use with Codex CLI
+# Run codex command in any directory
+# MCP tools will be available globally
+```
+
+**Example Configuration (~/.codex/config.toml):**
+```toml
+[mcp_servers.mcp-ticketer]
+command = "/path/to/mcp-ticketer"
+args = ["serve"]
+
+[mcp_servers.mcp-ticketer.env]
+PYTHONPATH = "/path/to/project/src"
+MCP_TICKETER_ADAPTER = "aitrackdown"
+MCP_TICKETER_BASE_PATH = "/path/to/project/.aitrackdown"
 ```
 
+**Limitations:**
+- ❌ No project-level configuration support
+- ❌ Global configuration affects all projects
+- ⚠️ Requires restart after configuration changes
+- ⚠️ TOML format (different from other clients)
+
+**Use when:**
+- You primarily work on one project
+- You need global MCP access across all directories
+- You prefer TOML configuration
+
+---
+
+### Auggie Integration
+
+**⚠️ IMPORTANT: Auggie only supports GLOBAL configuration**
+
+```bash
+# 1. Initialize mcp-ticketer
+make install-dev
+make init-aitrackdown
+
+# 2. Configure for Auggie (THE ONLY WAY)
+mcp-ticketer mcp auggie
+
+# 3. Configuration created at:
+# Global only: ~/.augment/settings.json
+
+# 4. Restart Auggie CLI
+# Auggie should pick up the new configuration
+
+# 5. Use with Auggie CLI
+# Run auggie command in any directory
+# MCP tools will be available globally
+```
+
+**Example Configuration (~/.augment/settings.json):**
+```json
+{
+  "mcpServers": {
+    "mcp-ticketer": {
+      "command": "/path/to/mcp-ticketer",
+      "args": ["serve"],
+      "env": {
+        "MCP_TICKETER_ADAPTER": "aitrackdown",
+        "MCP_TICKETER_BASE_PATH": "/Users/user/.mcp-ticketer/.aitrackdown"
+      }
+    }
+  }
+}
+```
+
+**Limitations:**
+- ❌ No project-level configuration support
+- ❌ Global configuration affects all projects
+- ⚠️ Uses global paths for adapter storage
+
+**Use when:**
+- You work on a single project primarily
+- You want simple, global MCP access
+- You prefer JSON configuration
+
+---
+
+### Comparison: Which Client Should You Use?
+
+| Feature | Claude Code | Gemini CLI | Codex CLI | Auggie |
+|---------|-------------|------------|-----------|--------|
+| **Project-level config** | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
+| **Global config** | ✅ Yes | ✅ Yes | ✅ Only option | ✅ Only option |
+| **Config format** | JSON | JSON | TOML | JSON |
+| **Hot reload** | ✅ Yes | ✅ Yes | ❌ Requires restart | ⚠️ May require restart |
+| **Security options** | ⚠️ Basic | ✅ Trust setting | ⚠️ Basic | ⚠️ Basic |
+| **Working directory** | ✅ Supported | ✅ Supported | ⚠️ Global only | ⚠️ Global only |
+| **Auto .gitignore** | ⚠️ Manual | ✅ Automatic | N/A | N/A |
+| **Maturity** | ✅ Stable | ✅ Stable | ⚠️ Beta | ⚠️ Emerging |
+
+**Recommendation:**
+- **Best choice**: Claude Code (native integration, project-level support)
+- **Alternative**: Gemini CLI (excellent project-level support, security features)
+- **Single project**: Codex CLI or Auggie (simple global setup)
+
+---
+
 ### Agent Collaboration Patterns
 
 **Multi-Agent Workflow:**

{mcp_ticketer-0.1.23 → mcp_ticketer-0.1.26}/CLAUDE_DESKTOP_SETUP.md

@@ -37,7 +37,7 @@ The configuration file at `~/.mcp-ticketer/config.json` controls which adapter i
 
 Test the MCP server:
 ```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /Users/masa/.local/bin/mcp-ticketer mcp
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /Users/masa/.local/bin/mcp-ticketer serve
 ```
 
 You should see a JSON response with the server information.
@@ -46,7 +46,7 @@ You should see a JSON response with the server information.
 
 For development, use the `mcp_server.sh` script in the project directory:
 ```bash
-./mcp_server.sh mcp
+./mcp_server.sh serve
 ```
 
 This script:

mcp_ticketer-0.1.26/CODEX_INTEGRATION.md

@@ -0,0 +1,312 @@
+# Codex CLI Integration for MCP Ticketer
+
+## Overview
+
+This document describes the Codex CLI integration for mcp-ticketer, which allows the Codex AI assistant to interact with mcp-ticketer through the Model Context Protocol (MCP).
+
+**Important**: Codex CLI only supports **global configuration** at `~/.codex/config.toml`. Unlike Claude Code and Gemini CLI, there is no project-level configuration support.
+
+## Quick Start
+
+### 1. Prerequisites
+
+- mcp-ticketer installed (`pip install mcp-ticketer` or `make install-dev`)
+- Project configured with `.mcp-ticketer/config.json` (run `mcp-ticketer init`)
+
+### 2. Configure Codex CLI
+
+```bash
+# Configure Codex CLI globally
+mcp-ticketer mcp codex
+
+# Or force overwrite existing configuration
+mcp-ticketer mcp codex --force
+```
+
+### 3. Restart Codex CLI
+
+**Important**: You must restart Codex CLI after configuration changes.
+
+### 4. Verify Configuration
+
+Check `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mcp-ticketer]
+command = "/path/to/mcp-ticketer"
+args = ["serve"]
+
+[mcp_servers.mcp-ticketer.env]
+PYTHONPATH = "/path/to/src"
+MCP_TICKETER_ADAPTER = "aitrackdown"
+MCP_TICKETER_BASE_PATH = "/path/to/.aitrackdown"
+```
+
+## Configuration Details
+
+### File Locations
+
+- **Codex Config**: `~/.codex/config.toml` (global only)
+- **MCP Ticketer Config**: `.mcp-ticketer/config.json` (project-local)
+
+### Configuration Scope
+
+| CLI Tool | Scope Options | Config Location |
+|----------|---------------|-----------------|
+| Claude Code | Project, Global | `.mcp/config.json` or `~/Library/Application Support/Claude/` |
+| Gemini CLI | Project, User | `.gemini/settings.json` or `~/.gemini/settings.json` |
+| **Codex CLI** | **Global only** | **`~/.codex/config.toml`** |
+
+### Environment Variables
+
+The configuration automatically includes environment variables based on your adapter:
+
+**AITrackdown (Local)**:
+- `MCP_TICKETER_ADAPTER=aitrackdown`
+- `MCP_TICKETER_BASE_PATH=/path/to/.aitrackdown`
+
+**Linear**:
+- `MCP_TICKETER_ADAPTER=linear`
+- `LINEAR_API_KEY=your_api_key`
+- `LINEAR_TEAM_ID=your_team_id`
+
+**GitHub**:
+- `MCP_TICKETER_ADAPTER=github`
+- `GITHUB_TOKEN=your_token`
+- `GITHUB_OWNER=owner`
+- `GITHUB_REPO=repo`
+
+**JIRA**:
+- `MCP_TICKETER_ADAPTER=jira`
+- `JIRA_API_TOKEN=your_token`
+- `JIRA_EMAIL=your_email`
+- `JIRA_SERVER=https://your-domain.atlassian.net`
+- `JIRA_PROJECT_KEY=PROJECT`
+
+## TOML Structure
+
+### Key Differences from JSON-based CLIs
+
+Codex uses TOML format with specific naming conventions:
+
+```toml
+# Codex uses underscore: mcp_servers (not camelCase mcpServers)
+[mcp_servers.mcp-ticketer]
+command = "/usr/local/bin/mcp-ticketer"
+args = ["serve"]
+
+# Environment variables in nested section
+[mcp_servers.mcp-ticketer.env]
+PYTHONPATH = "/path/to/src"
+MCP_TICKETER_ADAPTER = "aitrackdown"
+```
+
+Compare to Claude Code JSON:
+
+```json
+{
+  "mcpServers": {
+    "mcp-ticketer": {
+      "command": "/usr/local/bin/mcp-ticketer",
+      "args": ["serve"],
+      "env": {
+        "PYTHONPATH": "/path/to/src",
+        "MCP_TICKETER_ADAPTER": "aitrackdown"
+      }
+    }
+  }
+}
+```
+
+## CLI Command Reference
+
+```bash
+# Configure Codex CLI
+mcp-ticketer mcp codex [OPTIONS]
+
+# Options:
+#   --force, -f    Overwrite existing configuration
+#   --help         Show help message
+
+# Examples:
+mcp-ticketer mcp codex                    # Configure globally
+mcp-ticketer mcp codex --force            # Force overwrite
+mcp-ticketer mcp codex --help             # Show help
+```
+
+## Troubleshooting
+
+### Configuration Not Taking Effect
+
+**Problem**: Changes to config.toml not reflected in Codex CLI
+
+**Solution**: Restart Codex CLI. Configuration changes require a restart.
+
+### Wrong Adapter Active
+
+**Problem**: Codex using wrong ticket adapter
+
+**Solution**: Check `.mcp-ticketer/config.json` in your project:
+
+```bash
+# Show current configuration
+mcp-ticketer configure --show
+
+# Set different adapter
+mcp-ticketer configure --adapter linear
+```
+
+Then reconfigure Codex:
+
+```bash
+mcp-ticketer mcp codex --force
+```
+
+### Binary Not Found
+
+**Problem**: "Could not find mcp-ticketer binary"
+
+**Solution**: Ensure mcp-ticketer is installed and in PATH:
+
+```bash
+# Check installation
+which mcp-ticketer
+
+# Install if missing
+pip install mcp-ticketer
+
+# Or for development
+make install-dev
+```
+
+### Configuration Path Issues
+
+**Problem**: TOML file has incorrect paths
+
+**Solution**: Run configuration from your project directory:
+
+```bash
+cd /path/to/your/project
+mcp-ticketer mcp codex --force
+```
+
+## Implementation Details
+
+### File Structure
+
+```
+src/mcp_ticketer/cli/
+├── codex_configure.py    # Codex CLI configuration module
+├── mcp_configure.py      # Claude Code configuration (JSON)
+├── gemini_configure.py   # Gemini CLI configuration (JSON)
+└── main.py              # CLI commands including 'codex' command
+```
+
+### Dependencies
+
+Added to `pyproject.toml`:
+
+```toml
+dependencies = [
+    # ... existing dependencies ...
+    "tomli>=2.0.0; python_version<'3.11'",  # TOML reading (Python <3.11)
+    "tomli-w>=1.0.0",                       # TOML writing (all versions)
+]
+```
+
+### Key Functions
+
+**`codex_configure.py`**:
+
+- `find_codex_config()`: Returns `~/.codex/config.toml` path
+- `load_codex_config(config_path)`: Loads existing TOML or empty structure
+- `save_codex_config(config_path, config)`: Writes TOML with formatting
+- `create_codex_server_config(binary_path, project_config, cwd)`: Creates server config
+- `configure_codex_mcp(force)`: Main configuration function
+
+## Testing
+
+### Manual Test
+
+```bash
+# 1. Configure
+mcp-ticketer mcp codex
+
+# 2. Check TOML file
+cat ~/.codex/config.toml
+
+# 3. Verify structure
+python3 test_codex_config.py
+```
+
+### Automated Test
+
+Run the included test script:
+
+```bash
+python3 test_codex_config.py
+```
+
+Expected output:
+
+```
+✓ Created test TOML file: /tmp/...
+✓ TOML format validation passed
+✓ Structure validation passed
+✓ Value validation passed
+
+✅ All tests passed!
+```
+
+## Comparison with Other CLIs
+
+| Feature | Claude Code | Gemini CLI | Codex CLI |
+|---------|-------------|------------|-----------|
+| **Config Format** | JSON | JSON | **TOML** |
+| **Config Location** | Project or Global | Project or User | **Global only** |
+| **Key Name** | mcpServers | mcpServers | **mcp_servers** |
+| **Scope Flag** | `--global` | `--scope user/project` | **None (global only)** |
+| **Restart Required** | Yes | No | **Yes** |
+| **Nested Env** | Yes | Yes | Yes |
+| **Project Support** | Yes | Yes | **No** |
+
+## Security Considerations
+
+### Global Configuration Implications
+
+Since Codex only supports global configuration:
+
+1. **API Keys**: Environment variables (including API keys) are in global config
+2. **Path References**: Configuration includes absolute paths from configuration time
+3. **Multi-Project**: Same configuration used across all projects
+
+### Best Practices
+
+1. **Protect config.toml**: Ensure `~/.codex/config.toml` has appropriate permissions
+2. **Avoid Hardcoded Secrets**: Use environment variables where possible
+3. **Reconfigure Per Project**: Run `mcp-ticketer mcp codex --force` when switching projects
+4. **Review Configuration**: Periodically audit `~/.codex/config.toml`
+
+## Future Enhancements
+
+- [ ] Support for multiple adapters in single config
+- [ ] Environment variable templating
+- [ ] Automatic path resolution
+- [ ] Configuration validation command
+- [ ] Migration tool from JSON to TOML
+
+## References
+
+- [Codex CLI Documentation](https://github.com/your-org/codex-cli)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+- [TOML Specification](https://toml.io/en/)
+- [mcp-ticketer Documentation](https://github.com/mcp-ticketer/mcp-ticketer)
+
+## Support
+
+For issues or questions:
+
+1. Check troubleshooting section above
+2. Review `~/.codex/config.toml` for correctness
+3. Test with `mcp-ticketer mcp codex --force`
+4. File issue at https://github.com/mcp-ticketer/mcp-ticketer/issues