MCP Ticketer

MCP售票机

](https://pypi.org/project/mcp-ticketer) ](https://pypi.org/project/mcp-ticketer)     

支持MCP（模型上下文协议）的AI代理的通用票证管理接口。

🚀 特性

• 🎯 通用票模型：简化为史诗、任务和评论类型
• 🔌 多个适配器：支持JIRA、Linear、GitHub问题和AI追踪
• 🤖 MCP集成：原生支持AI代理交互
• ⚡ 高性能：智能缓存和异步操作
• 🎨 丰富的CLI：漂亮的终端界面，有颜色和表格
• 📊 状态机：内置状态转换和验证
• 🔍 高级搜索：使用多个过滤器的全文搜索
• 🔗 层次导航：父问题查找和过滤子问题检索
• 👤 智能分配：具有URL支持和审计跟踪的专用分配工具
• 🏷️ 标签管理：智能标签组织、重复数据删除和模糊匹配清理
• 📎 文件附件：上传、列出和管理工单附件（AITrackdown适配器）
• 📝 自定义指令：为您的团队定制工单编写指南
• 🔬 PM监控工具：检测重复的票，识别过时的工作，并找到孤立的票
• 📦 简易安装：可在PyPI上使用简单的pip安装
• 🚀 自动依赖安装：自动适配器依赖性检测和安装
• 💾 紧凑模式：AI代理票证列表查询的令牌减少70%（v0.15.0+）

⚡ 代币效率

MCP Ticketer针对AI代理的使用进行了优化，内置了令牌管理：

• 20k代币限额：所有工具响应保持在20000个令牌以下
• 自动分页：可能超出限制的工具支持分页
• 紧凑模式：最少的响应（15个令牌vs每张票185个）
• 渐进式披露：先总结，按需提供详细信息

看 📄 令牌分页 以下部分用于快速入门，或 docs/user docs/features/TOKEN_PAGINATION.md 获取详细的技术指南。

📦 安装

来自PyPI（推荐）

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

注释（v0.15.0+）：The setup 命令现在自动检测并安装适配器依赖项！当你奔跑时 mcp-ticketer setup，它将提示您安装任何缺少的适配器特定依赖项，从而消除了手动操作的需要 pip install mcp-ticketer[adapter] 设置后。

来源

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

需求

• Python 3.9+
• 虚拟环境（推荐）

PATH配置（可选但推荐）

为了实现最佳的Claude Desktop MCP集成，请确保 mcp-ticketer 在您的路径中：

pipx用户:

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

为什么要配置PATH？

• ✅ 使用PATH：原生Claude CLI集成，实现更好的用户体验
• ⚠️ 无路径：mcp ticketer仍然使用完整路径（传统模式）工作

验证PATH配置:

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

注释（v2.0.2+）：安装程序会自动检测以下情况 mcp-ticketer 位于PATH中，并适当配置Claude Desktop。看 1米-579 了解技术细节。

🤖 支持的AI客户端

MCP Ticketer通过模型上下文协议（MCP）与多个AI客户端集成：

快速MCP设置

# 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

安装范围（v1.4+）

默认情况下， mcp-ticketer install 专注于 仅限代码编辑器:

• ✅ 克劳德代码
• ✅ 光标
• ✅ 奥吉
• ✅ 法典
• ✅ 双子座

为什么只有代码编辑器？ 代码编辑器是为处理代码库而设计的项目范围的工具。Claude Desktop是一款通用的人工智能助手。这种分离确保了mcp ticketer被配置在提供最大价值的地方。

包括克劳德桌面:

要安装Claude Desktop（AI助手），请使用 --include-desktop 标志：

# 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

看 AI客户端集成指南 有关详细的设置说明。

🚀 快速开始

1.初始化配置

# 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 init -初始化配置
• mcp-ticketer install -安装和配置（与init相同）
• mcp-ticketer setup -安装程序（与init相同）

自动验证

init命令现在会在安装后自动验证您的配置：

• 有效凭证→ 安装程序立即完成
• 无效凭证→ 系统将提示您：

1. 重新进入配置（最多重试3次） 1. 仍继续（跳过验证） 1. 退出并手动修复

您始终可以稍后通过以下方式重新验证： mcp-ticketer doctor

2.创建您的第一张票

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

3.门票管理

# 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

4.使用附件（AITrackdown）

# 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"

有关程序化访问，请参阅 附件指南.

5.自定义票务书写说明

根据团队惯例自定义门票指南：

# 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

有关详细信息，请参阅 门票说明指南.

6.PM监控工具

使用自动分析和清理工具维护票证健康状况：

# 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

可用的MCP工具：

• ticket_find_similar -使用TF-IDF和余弦相似度检测重复票
• ticket_find_stale -识别可能需要关闭的非活动票证
• ticket_find_orphaned -查找没有适当层次结构的门票
• ticket_cleanup_report -生成综合分析报告

主要特点：

• 相似性检测：具有模糊匹配和标签重叠的TF-IDF矢量化
• 稳定性评分：多因素分析（年龄、不活动、优先级、状态）
• 孤立检测：识别缺少父级史诗或项目的门票
• 可操作的见解：自动建议合并、链接、关闭或分配操作

有关完整文档，请参阅 PM监控工具指南.

7.线性实用工作流CLI

使用常见操作的命令行快捷方式简化您的日常线性工作流程：

# 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

主要特点：

• 自动标记：自动应用 bug, feature，或 task 标签
• 快速命令：作为单个命令的常见工作流操作
• 评论跟踪：直接从CLI添加和列出注释
• 环境验证：内置配置检查

设置：

# 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

有关完整文档，请参阅 线性工作流CLI指南.

8.项目状态更新

通过Linear、GitHub V2和Asana的状态更新跟踪项目进度：

# 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"

主要特点：

• 健康指标：5个状态级别（ontrack、at_risk、off_track、complete、inactive）
• 灵活的项目ID：支持UUID、slug ID、短ID或完整URL
• 丰富的格式：颜色编码的健康指标和格式化表格
• MCP工具：通过程序访问 project_update_create, project_update_list, project_update_get
• 交叉平台的：线性（原生）、GitHub V2、Asana、Jira（变通方法）

有关完整文档，请参阅 线性设置指南.

📄 令牌分页（v1.3.1）

概述

mcp-ticketer实现了智能令牌分页，以防止在处理大型数据集时发生上下文溢出。MCP服务器会自动对超过20000个令牌的响应进行分页，确保Claude对话保持响应和高效。

为什么分页很重要

使用大额票系统可以快速消耗您的AI上下文窗口：

• 上下文保护：大型票单可能消耗50k+代币，几乎没有对话空间
• 演出：在获取100多张票时防止超时错误
• 可靠性：无论数据集大小如何，都能保证可预测的响应大小
• 效率：允许使用包含500多个票证的项目，而不会发生上下文溢出

快速开始

分页是 自动的 -你不需要配置任何东西。当响应接近20k令牌时，工具会智能分页：

# 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)

分页MCP工具

以下工具支持具有智能限制的自动令牌分页：

备注：所有工具均不超过每次响应20000个令牌的限制。

使用示例

示例1：基本票列表（最优）

# 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
}

示例2：获取更多数据（续）

# 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...

示例3：处理大型项目（500+张门票）

# 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...

示例4：分页搜索

# 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']})")

代币优化提示

默认情况下使用紧凑模式 （代币减少70%）：

# ✅ 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
}

了解更多

• 综合指南: docs/user docs/features/TOKEN_PAGINATION.md -详细的技术文档

- 令牌估计算法 - 每工具优化策略 - 高级分页模式 - 故障排除指南

• 代码示例: examples/token_pagination.example.py -可运行的示例
• 从v1.2.x迁移：无中断更改-现有代码可自动分页

______________________________________________________________________

🎯 项目状态分析（v1.3.0中的新功能）

通过自动依赖性分析、阻断检测和智能建议，获得智能项目健康评估和可操作的工作计划。

概述

项目状态分析功能为PM代理提供全面的项目洞察：

• 健康评估：自动评分（在线、at_risk、离线）
• 相关性分析：关键路径检测和阻断器识别
• 智能推荐：接下来从推理开始的前三张票
• 工作分配：团队工作量分析和平衡检查
• 进度跟踪：完成率和时间表风险评估

快速开始

# 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"
  ]
}

特性

🏥 健康评估

基于以下内容的自动项目健康评分：

• 完成率：已完成门票的百分比
• 进度率：%的票有效
• 阻断率：被阻止的门票百分比（负面因素）
• 优先级平衡：关键/高优先级完成

健康水平：

• on_track：项目进展顺利（健康评分≥0.7）
• at_risk：一些问题，需要监测（0.4-0.7）
• off_track：严重问题，需要干预（\高>中>低）

1. 影响 （阻止其他人的票得分更高）
2. 关键路径 （最长链上的票优先）
3. 阻碍 （首选未堵塞的门票）
4. 状态 （开放/就绪门票排名较高）

返回前3张票，以明确的理由开始下一张票。

👥 工作分配分析

团队工作量分析显示：

• 每位受让人的门票
• 每个受让人的州细分
• 工作量不平衡检测

使用示例

基本项目健康检查

# 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']}")

PM日常站立工作流程

# 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']}"
    )

了解更多

• 综合指南: docs/meta/PROJECT_STATUS.md -完整文档
• 可运行示例: examples/project_status.example.py -复制粘贴代码
• PM监控工具: docs/PM_MONITOING_TOOLS.md -票证清理功能
• 线性设置: docs/integrations/setup/LINEAR_setup.md -平台特定指南

🤖 MCP服务器集成

MCP Ticketer通过自动配置和平台检测提供与AI客户端的无缝集成：

# 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

配置是自动的 -上述命令将：

1. 检测您的mcp票证安装
2. 读取适配器配置
3. 生成适当的MCP服务器配置
4. 将其保存到您的AI客户端的正确位置

Claude代码安装

自动（推荐）:

mcp-ticketer install --platform claude-code

安装程序会自动检测您是否安装了Claude CLI：

• 使用Claude CLI：使用本地 claude mcp add 命令（推荐）
• 没有Claude CLI：返回JSON配置

手动安装 （如果需要）：

# 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

备注：Claude CLI提供了更好的验证和错误处理。 从以下位置安装：https://docs.claude.ai/cli

有关本机CLI支持的全面详细信息，请参阅 Claude代码原生CLI功能文档.

手动配置示例 （克劳德代码）：

Claude Code支持两个具有自动检测功能的配置文件位置：

选项1：全局配置 (~/.config/claude/mcp.json) - 推荐

{
  "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"
      }
    }
  }
}

选项2：项目特定配置 (~/.claude.json)

{
  "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"
          }
        }
      }
    }
  }
}

配置优先级：

• 新地点(~/.config/claude/mcp.json)先检查
• 回到原来的位置(~/.claude.json)如果未找到新位置
• 保持与现有配置的完全向后兼容性
• 这两个地点都得到了充分支持

为什么是这种模式？

• 可靠的：直接使用venv Python而不是二进制包装器
• 一致的：匹配经过验证的mcp向量搜索模式
• 通用：适用于pipx、pip和uv安装
• 更好的错误：Python模块调用提供了更清晰的错误消息

自动检测：The mcp-ticketer install 命令会自动检测您的venv-Python、配置位置，并生成正确的配置格式。

看 AI客户端集成指南 了解客户特定的详细信息。

💾 AI代理的紧凑模式（v0.15.0+）

这 ticket_list MCP工具支持紧凑模式，通过以下方式减少令牌使用 70% 在列出门票时-非常适合处理大额门票的人工智能代理。紧凑模式是更广泛模式的一部分 令牌分页 v1.3.1中引入的系统。

快速参考

基本用法

# 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

字段已返回

紧凑模式（7个字段）：

• id, title, state, priority, assignee, tags, parent_epic

标准模式（16个字段）：

• 所有紧凑型场地加上： description, created_at, updated_at, metadata, ticket_type, estimated_hours, actual_hours, children, parent_issue

了解更多

• 令牌分页：参见 📄 令牌分页 分页、令牌优化和最佳实践综合指南部分
• 技术细节: docs/user docs/features/TOKEN_PAGINATION.md -每工具令牌估计和优化策略
• 快速摘要: COMPACT_MODE_SUMMARY.md -紧凑型模式参考

⚙️ 配置

使用MCP工具快速设置（v1.x中的新功能）

简化配置：新的MCP工具将适配器设置时间从15-30分钟缩短到\ 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

**备注**：该项目包括一个预配置的 `.venv` 所有的依赖关系。只需激活它即可开始。

**排除pytest问题？** 看 [开发环境指南](docs/DEVELOPMENT_ENVIRONMENT.md) 了解详细的设置说明和常见问题解决方案。

### 模块化构建系统

mcp票务员使用 **模块化Makefile架构** 简化开发工作流程。构建系统被组织成专门的模块，用于质量、测试、发布、文档和MCP特定的操作。

**快速开始**:

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

**主要特点**:

- ⚡ **并行测试**：速度提高3-4x `make test-parallel`
- 📊 **增强的帮助**：带有描述的分类目标
- 🎯 **70+目标**：按模块组织（测试、质量、发布、文档、MCP）
- 🔧 **生成元数据**：使用生成构建信息 `make build-metadata`
- 📋 **模块反思**：查看加载的模块 `make modules`

**常用命令**:

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 (Ruff) 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

**构建系统详细信息**:

- 看 [.makefiles/README.md](.makefiles/README.md) 获取完整的模块文档
- 看 [.makefiles/QUICK_REFERENCE.md](.makefiles/QUICK_REFERENCE.md) 用于快速命令参考
- 看 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) 全面发展指南

### 运行测试

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

**性能比较**:

- 串行执行：~30-60秒
- 并行（4核）：~8-15秒(**速度快3-4x**)

### 代码质量

Using Makefile (recommended)

make lint # Run Ruff and MyPy make lint-fix # Auto-fix issues make format # Format with Ruff make typecheck # Type checking with MyPy make quality # All quality checks

Direct commands (still supported)

ruff format 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

## 📋 路线图

### ✅ v0.1.0（当前）

- 核心票模型和状态机
- JIRA、Linear、GitHub、AITrackdown适配器
- 丰富的CLI界面
- 用于AI集成的MCP服务器
- 智能缓存系统
- 全面的测试套件

### 🚧 v0.2.0（开发中）

- \[\]Web UI仪表板
- \[\]Webhook支持
- \[\]高级搜索
- \[\]团队协作
- \[\]批量操作
- \[\]API速率限制

### 🔮 v0.3.0+（未来）

- \[\]GitLab发布适配器
- \[\]Slack/团队集成
- \[\]自定义适配器SDK
- \[\]分析仪表板
- \[\]移动应用程序
- \[\]企业SSO

## 🤝 贡献

我们欢迎捐款！请查看我们的 [贡献指南](CONTRIBUTING.md) 了解详情。

1. 分叉存储库
1. 创建功能分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求

## 📄 许可证

此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。

## 🙏 致谢

- 建于 [派丹蒂克](https://pydantic-docs.helpmanual.io/) 用于数据验证
- CLI由 [类型](https://typer.tiangolo.com/) 和 [富有的](https://rich.readthedocs.io/)
- MCP集成使用 [模型上下文协议](https://github.com/anthropics/model-context-protocol)

## 📞 支持

- 📧 电子邮件：support@mcp-ticketer.io
- 💬 不一致： [加入我们的社区](https://discord.gg/mcp-ticketer)
- 🐛 问题： 
- 📖 文件： [阅读文档](https://mcp-ticketer.readthedocs.io)

## ⭐ 星迹

[![Star History Chart](https://api.star-history.com/svg?repos=mcp-ticketer/mcp-ticketer&type=Date)](https://star-history.com/#mcp-ticketer/mcp-ticketer&Date)

______________________________________________________________________

制作❤️ MCP票务团队