AI代理票务管理接口

pip install mcp-ticketer

# Install with specific adapters
pip install mcp-ticketer[jira]      # JIRA support
pip install mcp-ticketer[linear]    # Linear support
pip install mcp-ticketer[github]    # GitHub Issues support
pip install mcp-ticketer[analysis]  # PM monitoring tools
pip install mcp-ticketer[all]       # All adapters and features

git clone https://github.com/mcp-ticketer/mcp-ticketer.git
cd mcp-ticketer
pip install -e .

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc to make permanent

export PATH="$HOME/.local/bin:$PATH"  # Linux/macOS
# Add to ~/.bashrc or ~/.zshrc to make permanent

which mcp-ticketer
# Should show: /Users/username/.local/bin/mcp-ticketer (or similar)

# Initialize adapter first (required)
mcp-ticketer init --adapter aitrackdown

# Auto-detection (Recommended) - Interactive platform selection
mcp-ticketer install                       # Auto-detect and prompt for platform

# See all detected platforms
mcp-ticketer install --auto-detect         # Show what's installed on your system

# Install for all detected platforms at once
mcp-ticketer install --all                 # Configure all detected code editors

# Or install for specific platform
mcp-ticketer install claude-code           # Claude Code (project-level)
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

# Install for all platforms including Claude Desktop
mcp-ticketer install --all --include-desktop

# Auto-detect including Claude Desktop
mcp-ticketer install --auto-detect --include-desktop

# Install ONLY Claude Desktop
mcp-ticketer install claude-desktop

# For AI-Trackdown (local file-based)
mcp-ticketer init --adapter aitrackdown

# For Linear (requires API key)
# Option 1: Using team URL (easiest - paste your Linear team issues URL)
mcp-ticketer init --adapter linear --team-url https://linear.app/your-org/team/ENG/active

# Option 2: Using team key
mcp-ticketer init --adapter linear --team-key ENG

# Option 3: Using team ID
mcp-ticketer init --adapter linear --team-id YOUR_TEAM_ID

# For JIRA (requires server and credentials)
mcp-ticketer init --adapter jira \
  --jira-server https://company.atlassian.net \
  --jira-email your.email@company.com

# For GitHub Issues
mcp-ticketer init --adapter github --repo owner/repo

mcp-ticketer create "Fix login bug" \
  --description "Users cannot login with OAuth" \
  --priority high \
  --assignee "john.doe"

# List open tickets
mcp-ticketer list --state open

# Show ticket details
mcp-ticketer show TICKET-123 --comments

# Update ticket
mcp-ticketer update TICKET-123 --priority critical

# Transition state
mcp-ticketer transition TICKET-123 in_progress

# Search tickets
mcp-ticketer search "login bug" --state open

# Working with attachments through MCP
# (Requires MCP server running - see MCP Server Integration section)

# Attachments are managed through your AI client when using MCP
# Ask your AI assistant: "Add the document.pdf as an attachment to task-123"

# View current instructions
mcp-ticketer instructions show

# Add custom instructions from file
mcp-ticketer instructions add team_guidelines.md

# Edit instructions interactively
mcp-ticketer instructions edit

# Reset to defaults
mcp-ticketer instructions delete --yes

# Our Team's Ticket Guidelines

## Title Format
[TEAM-ID] [Type] Brief description

## Required Sections
1. Problem Statement
2. Acceptance Criteria (minimum 3)
3. Testing Notes

# Install analysis dependencies first
pip install "mcp-ticketer[analysis]"

# Find duplicate or similar tickets
mcp-ticketer analyze similar --threshold 0.8

# Identify stale tickets that may need closing
mcp-ticketer analyze stale --age-days 90 --inactive-days 30

# Find orphaned tickets without parent epic/project
mcp-ticketer analyze orphaned

# Generate comprehensive cleanup report
mcp-ticketer analyze cleanup --format markdown

# Quick ticket creation with auto-tagging
./ops/scripts/linear/practical-workflow.sh create-bug "Login fails" "Error 500" --priority high
./ops/scripts/linear/practical-workflow.sh create-feature "Dark mode" "Add theme toggle"
./ops/scripts/linear/practical-workflow.sh create-task "Update docs" "Refresh API docs"

# Workflow shortcuts
./ops/scripts/linear/practical-workflow.sh start-work BTA-123
./ops/scripts/linear/practical-workflow.sh ready-review BTA-123
./ops/scripts/linear/practical-workflow.sh deployed BTA-123

# Comments
./ops/scripts/linear/practical-workflow.sh add-comment BTA-123 "Working on this now"
./ops/scripts/linear/practical-workflow.sh list-comments BTA-123

# Copy configuration template
cp ops/scripts/linear/.env.example .env

# Edit with your Linear API key and team key
# LINEAR_API_KEY=lin_api_...
# LINEAR_TEAM_KEY=BTA

# Test configuration
./ops/scripts/linear/practical-workflow.sh --help

# Create update with health indicator
mcp-ticketer project-update create "mcp-ticketer-eac28953c267" \
  "Completed MCP tools implementation. CLI commands in progress." \
  --health on_track

# Create update using full URL
mcp-ticketer project-update create \
  "https://linear.app/1m-hyperdev/project/mcp-ticketer-eac28953c267/updates" \
  "Sprint review completed successfully" \
  --health on_track

# List recent updates
mcp-ticketer project-update list "mcp-ticketer-eac28953c267" --limit 10

# Get detailed update
mcp-ticketer project-update get "update-uuid-here"

# Compact mode (default) - Minimal token usage
tickets = await ticket_list(limit=20, compact=True)  # ~300 tokens

# Full mode - When you need all details
tickets = await ticket_list(limit=20, compact=False)  # ~3,700 tokens

# Large datasets - Automatic pagination kicks in
labels = await label_list(limit=100)  # ~1,500 tokens (safe)

# Default settings optimized for AI agents
result = await ticket_list()  # Uses limit=20, compact=True
# Returns ~300 tokens - perfect for conversations

# Response includes:
{
    "items": [...],              # Tickets with id, title, state, priority, assignee
    "count": 20,                 # Items in this response
    "total": 150,                # Total tickets available
    "has_more": True,            # More pages exist
    "estimated_tokens": 300      # Approximate token usage
}

# Get first page
page1 = await ticket_list(limit=50, offset=0, compact=True)
print(f"Showing {page1['count']} of {page1['total']} tickets")
# ~750 tokens (safe)

# Check if more pages exist
if page1['has_more']:
    # Get next page
    page2 = await ticket_list(limit=50, offset=50, compact=True)
    # Continue paginating as needed...

# Progressive disclosure pattern for large projects
# 1. Start with summary (minimal tokens)
summary = await ticket_cleanup_report(summary_only=True)  # ~1k tokens
print(f"Project has {summary['total_issues']} potential issues")

# 2. Get compact list to filter
tickets = await ticket_list(
    state="in_progress",
    priority="high",
    limit=20,
    compact=True  # Only 300 tokens
)

# 3. Fetch full details only for selected tickets
for ticket_summary in tickets['items'][:5]:  # Top 5 only
    full_ticket = await ticket_read(ticket_summary['id'])  # ~200 tokens each
    # Process full ticket details...

# Search returns paginated results automatically
results = await ticket_search(
    query="authentication bug",
    state="open",
    limit=10  # Safe limit for search results
)
# ~3k-5k tokens (includes relevance scoring)

# Access results
for ticket in results['items']:
    print(f"{ticket['id']}: {ticket['title']} (score: {ticket['relevance_score']})")

# ✅ Good: Compact mode for browsing
tickets = await ticket_list(limit=50, compact=True)  # ~750 tokens

# ❌ Avoid: Full mode with large limits
tickets = await ticket_list(limit=100, compact=False)  # ~18,500 tokens (too close to limit!)

# ✅ Good: Summary first, details on demand
summary = await ticket_list(limit=50, compact=True)
# Then fetch full details only for tickets you need
for ticket in important_tickets:
    details = await ticket_read(ticket['id'])

# ✅ Good: Process in batches
all_labels = []
offset = 0
while True:
    batch = await label_list(limit=100, offset=offset)
    all_labels.extend(batch['labels'])
    if not batch['has_more']:
        break
    offset += 100

# Adjust limit per tool (within safe maximums)
tickets = await ticket_list(limit=50)  # Increase from default 20

# Use compact mode to maximize items per response
tickets = await ticket_list(limit=100, compact=True)  # Safe with compact mode

# Use summary_only for analysis tools
report = await ticket_cleanup_report(summary_only=True)  # Minimal tokens

{
    "status": "completed",
    "items": [...],                    # Results (tickets, labels, etc.)
    "count": 20,                       # Items in this response
    "total": 150,                      # Total items available (if known)
    "offset": 0,                       # Offset used for this page
    "limit": 20,                       # Limit used for this page
    "has_more": true,                  # Whether more pages exist
    "truncated_by_tokens": false,      # Whether token limit was hit before item limit
    "estimated_tokens": 2500           # Approximate tokens in response
}

# Get project status analysis (uses default_project from config)
result = await project_status()

# Analyze specific project
result = await project_status(project_id="eac28953c267")

{
  "status": "success",
  "project_id": "eac28953c267",
  "project_name": "MCP Ticketer",
  "health": "at_risk",
  "summary": {
    "total": 12,
    "open": 5,
    "in_progress": 4,
    "done": 3
  },
  "recommended_next": [
    {
      "ticket_id": "1M-317",
      "title": "Fix critical bug",
      "priority": "critical",
      "reason": "Critical priority, Unblocks 2 tickets",
      "blocks": ["1M-315", "1M-316"]
    }
  ],
  "recommendations": [
    "🔓 Resolve 1M-317 first (critical) - Unblocks 2 tickets",
    "⚡ Project is AT RISK - Monitor closely"
  ]
}

# Get health of default project
status = await project_status()

print(f"Health: {status['health']}")
print(f"Total tickets: {status['summary']['total']}")
print(f"Completion: {status['health_metrics']['completion_rate']:.1%}")

# Analyze by project ID
status = await project_status(project_id="eac28953c267")

# Check for critical issues
if status['health'] == 'off_track':
    print("⚠️ Project needs immediate attention!")
    for rec in status['recommendations']:
        print(f"  • {rec}")

# Get recommended tickets to work on
status = await project_status()

print("Top priorities:")
for ticket in status['recommended_next']:
    print(f"  {ticket['ticket_id']}: {ticket['title']}")
    print(f"    Priority: {ticket['priority']}")
    print(f"    Reason: {ticket['reason']}")
    if ticket['blocks']:
        print(f"    Unblocks: {', '.join(ticket['blocks'])}")

# Find what's blocking progress
status = await project_status()

if status['blockers']:
    print("🚧 Active blockers:")
    for blocker in status['blockers']:
        print(f"  {blocker['ticket_id']}: {blocker['title']}")
        print(f"    Blocking {blocker['blocks_count']} tickets")
        print(f"    State: {blocker['state']}, Priority: {blocker['priority']}")

# Complete PM workflow for daily standup
async def daily_standup():
    status = await project_status()

    # 1. Overall health
    print(f"📊 Project Health: {status['health'].upper()}")
    print(f"   Completion: {status['health_metrics']['completion_rate']:.0%}")
    print(f"   In Progress: {status['summary'].get('in_progress', 0)} tickets")

    # 2. Blockers
    if status['blockers']:
        print(f"\n🚧 {len(status['blockers'])} Active Blockers:")
        for blocker in status['blockers'][:3]:
            print(f"   • {blocker['ticket_id']}: {blocker['title']}")

    # 3. Next actions
    print(f"\n🎯 Top Priorities:")
    for ticket in status['recommended_next']:
        print(f"   • {ticket['ticket_id']}: {ticket['reason']}")

    # 4. Recommendations
    print(f"\n💡 Recommendations:")
    for rec in status['recommendations']:
        print(f"   • {rec}")

# Via CLI
mcp-ticketer config set-project eac28953c267

# Via MCP tool
result = await config_set_default_project(project_id="eac28953c267")

status = await project_status()
metrics = status['health_metrics']

print(f"Health Score: {metrics['health_score']:.2f}/1.00")
print(f"Completion Rate: {metrics['completion_rate']:.1%}")
print(f"Progress Rate: {metrics['progress_rate']:.1%}")
print(f"Blocked Rate: {metrics['blocked_rate']:.1%}")
print(f"Critical Tickets: {metrics['critical_count']}")
print(f"High Priority: {metrics['high_count']}")

status = await project_status()

if status['critical_path']:
    print("🛣️ Critical Path (longest dependency chain):")
    for ticket_id in status['critical_path']:
        print(f"  → {ticket_id}")
    print(f"\nLength: {len(status['critical_path'])} tickets")

status = await project_status()

print("👥 Work Distribution:")
for assignee, workload in status['work_distribution'].items():
    print(f"\n{assignee}:")
    print(f"  Total: {workload['total']}")
    for state, count in workload.items():
        if state != 'total':
            print(f"  {state}: {count}")

# 1. Analyze project status
status = await project_status(project_id="proj-123")

# 2. Create status update with health indicator
update = await project_update_create(
    project_id="proj-123",
    body=f"Sprint review: {status['summary']['done']} tickets completed",
    health=status['health']  # Use analyzed health
)

# 1. Get recommendations
status = await project_status()

# 2. Auto-assign top priority ticket
if status['recommended_next']:
    top_ticket = status['recommended_next'][0]
    await ticket_assign(
        ticket_id=top_ticket['ticket_id'],
        assignee="john.doe@example.com",
        comment=f"Priority: {top_ticket['reason']}"
    )

# Auto-detection (Recommended)
mcp-ticketer install                       # Interactive: detect and prompt for platform
mcp-ticketer install --auto-detect         # Show all detected AI platforms
mcp-ticketer install --all                 # Install for all detected platforms
mcp-ticketer install --all --dry-run       # Preview what would be installed

# Platform-specific installation
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

# Manual MCP server control (advanced)
mcp-ticketer mcp                           # Start MCP server in current directory
mcp-ticketer mcp --path /path/to/project   # Start in specific directory

# Remove MCP configuration when needed
mcp-ticketer remove claude-code            # Remove from Claude Code
mcp-ticketer uninstall auggie              # Alias for remove

mcp-ticketer install --platform claude-code

# If you have Claude CLI installed
claude mcp add --scope local --transport stdio mcp-ticketer \
  -- mcp-ticketer mcp --path $(pwd)

# Or configure manually via JSON (legacy method)
# See manual configuration example below for details

{
  "mcpServers": {
    "mcp-ticketer": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "mcp_ticketer.mcp.server"],
      "env": {
        "MCP_TICKETER_ADAPTER": "linear",
        "LINEAR_API_KEY": "your_key_here"
      }
    }
  }
}

{
  "projects": {
    "/absolute/path/to/project": {
      "mcpServers": {
        "mcp-ticketer": {
          "command": "/path/to/venv/bin/python",
          "args": ["-m", "mcp_ticketer.mcp.server", "/absolute/path/to/project"],
          "env": {
            "PYTHONPATH": "/absolute/path/to/project",
            "MCP_TICKETER_ADAPTER": "aitrackdown"
          }
        }
      }
    }
  }
}

# Compact mode (recommended default)
result = await ticket_list(limit=100, compact=True)  # ~5,500 tokens

# Full mode (when you need all details)
result = await ticket_list(limit=20, compact=False)  # ~3,700 tokens

# 1. List available adapters with configuration status
result = await config_list_adapters()
# Shows: linear, github, jira, aitrackdown - which are configured

# 2. Get requirements for your adapter
requirements = await config_get_adapter_requirements("linear")
# Shows: api_key (required), team_id (optional)

# 3. Configure adapter with one-call setup wizard
result = await config_setup_wizard(
    adapter_type="linear",
    credentials={
        "api_key": "lin_api_...",
        "team_id": "ENG"  # or team UUID
    }
)
# Validates, tests connection, and saves configuration

# Paste your Linear team issues URL during setup
mcp-ticketer init --adapter linear --team-url https://linear.app/your-org/team/ENG/active

# The system automatically extracts the team key and resolves it to the team ID

# In .env or environment
LINEAR_API_KEY=lin_api_...
LINEAR_TEAM_KEY=ENG

# In .env or environment
LINEAR_API_KEY=lin_api_...
LINEAR_TEAM_ID=02d15669-7351-4451-9719-807576c16049

mcp-ticketer/
├── adapters/        # Ticket system adapters
│   ├── jira/       # JIRA integration
│   ├── linear/     # Linear integration
│   ├── github/     # GitHub Issues
│   └── aitrackdown/ # Local file storage
├── core/           # Core models and interfaces
├── cli/            # Command-line interface
├── mcp/            # MCP server implementation
├── cache/          # Caching layer
└── queue/          # Queue system for async operations

graph LR
    OPEN --> IN_PROGRESS
    IN_PROGRESS --> READY
    IN_PROGRESS --> WAITING
    IN_PROGRESS --> BLOCKED
    WAITING --> IN_PROGRESS
    BLOCKED --> IN_PROGRESS
    READY --> TESTED
    TESTED --> DONE
    DONE --> CLOSED

# Clone repository
git clone https://github.com/mcp-ticketer/mcp-ticketer.git
cd mcp-ticketer

# Activate existing virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,test,docs]"

# Install pre-commit hooks
pre-commit install

# Show all available commands
make help

# Complete development setup
make setup

# Run tests in parallel (3-4x faster)
make test-parallel

# Run all quality checks
make quality

# View project information
make info

# Testing
make test               # Run all tests (serial)
make test-parallel      # Run tests in parallel (3-4x faster)
make test-fast          # Parallel tests with fail-fast
make test-coverage      # Tests with HTML coverage report

# Code Quality
make lint               # Run linters (Ruff + MyPy)
make lint-fix           # Auto-fix linting issues
make format             # Format code (Black + isort)
make typecheck          # Run MyPy type checking
make quality            # Run all quality checks

# Release
make check-release      # Validate release readiness
make release-patch      # Bump patch version and publish
make release-minor      # Bump minor version and publish

# Documentation
make docs               # Build documentation
make docs-serve         # Serve docs at localhost:8000
make docs-open          # Build and open in browser

# Quick testing (recommended for development)
make test-parallel      # Parallel execution (3-4x faster)
make test-fast          # Parallel with fail-fast

# Standard pytest commands (still supported)
pytest                  # Run all tests
pytest --cov=mcp_ticketer --cov-report=html  # With coverage
pytest tests/test_adapters.py  # Specific test file
pytest -n auto          # Manual parallel execution

# Using Makefile (recommended)
make lint               # Run Ruff and MyPy
make lint-fix           # Auto-fix issues
make format             # Format with Black and isort
make typecheck          # Type checking with MyPy
make quality            # All quality checks

# Direct commands (still supported)
black src tests         # Format code
ruff check src tests    # Lint code
mypy src                # Type checking
tox                     # Run all checks

# Using Makefile (recommended)
make docs               # Build documentation
make docs-serve         # Serve at localhost:8000
make docs-open          # Build and open in browser

# Direct command (still supported)
cd docs && make html    # View at docs/_build/html/index.html