项目简介

MCP Ticketer是一个强大的工具，它为AI代理提供了一个统一的接口来访问和操作不同的项目管理系统（如JIRA、Linear、GitHub Issues等）中的票证（任务、问题、史诗）。它基于Model Context Protocol (MCP) 构建，允许大型语言模型 (LLM) 以标准化的方式获取项目上下文信息，调用工具创建、更新、查询票证，甚至管理团队的工作流程指令。通过缓存和异步操作，它确保了高性能和低延迟。

主要功能点

通用票证模型： 简化任务模型为史诗(Epic)、任务(Task)和评论(Comment)，便于AI理解和操作。
多适配器支持： 无缝连接JIRA、Linear、GitHub Issues和AI-Trackdown（本地文件存储）等多个平台。
AI代理集成： 原生支持MCP协议，允许AI代理直接与票证系统交互，执行创建、读取、更新、状态转换等操作。
智能缓存与高性能： 内置智能缓存和异步操作，确保数据访问的快速响应。
丰富的命令行界面 (CLI) 工具： 提供命令行界面，方便用户手动管理票证和配置。
状态机管理： 内置状态转换和验证机制，确保工作流程的正确性。
项目监控工具： 提供查找重复票证、识别过期工作、发现孤立票证等功能，帮助项目经理维护项目健康。
可定制指令： 允许团队定制票证撰写指南，确保AI代理生成的票证符合团队规范。
附件管理： 支持上传、列出和管理票证附件（目前主要通过AI-Trackdown适配器）。
紧凑模式： 为AI代理的票证列表查询提供紧凑模式，大幅减少LLM的Token消耗，提高效率。

安装步骤

MCP Ticketer支持通过pip轻松安装，建议在Python虚拟环境中进行。

创建并激活虚拟环境（推荐）：

python3 -m venv .venv
source .venv/bin/activate

从PyPI安装（推荐）： 安装核心功能：

pip install mcp-ticketer

如果您需要与特定的项目管理系统集成，可以安装相应的适配器（可选）：

pip install mcp-ticketer[jira]      # JIRA支持
pip install mcp-ticketer[linear]    # Linear支持
pip install mcp-ticketer[github]    # GitHub Issues支持
pip install mcp-ticketer[analysis]  # PM监控工具
pip install mcp-ticketer[all]       # 安装所有适配器和功能

注意： 安装后运行 'mcp-ticketer setup' 命令时，系统会自动检测并提示您安装任何缺失的适配器特定依赖。

服务器配置（为MCP客户端提供）

MCP Ticketer作为一个MCP服务器运行。您的MCP客户端（例如Claude Code、Gemini CLI等）需要知道如何启动它并与其通信。通常，这涉及在MCP客户端的配置文件中添加一个MCP服务器条目，该条目会指示客户端如何调用MCP Ticketer服务器。以下是配置的关键信息和参数说明：

服务器名称 ('server name'): 您可以为这个MCP Ticketer实例指定一个唯一的名称，例如 'mcp-ticketer'。这是客户端用来引用这个服务器的标识符。
启动命令 ('command'): 这是启动MCP Ticketer服务器的Python可执行文件路径。您需要将其指向您安装MCP Ticketer的虚拟环境中的Python解释器。
- 示例路径: '/path/to/your/virtualenv/bin/python'
命令参数 ('args'): 这些是传递给Python启动命令的参数，用于指定运行MCP Ticketer的服务器模块。
- 固定值: '"-m", "mcp_ticketer.mcp.server"'
环境变量 ('env'): 您可以在这里设置MCP Ticketer服务器运行时需要的环境变量，例如适配器的API密钥或默认设置。
- 'MCP_TICKETER_ADAPTER': 指定MCP Ticketer应该默认使用的适配器类型，例如 'linear', 'jira', 'github' 或 'aitrackdown'。
- 'LINEAR_API_KEY': 如果使用Linear适配器，需要您的Linear API密钥。
- 'LINEAR_TEAM_KEY' 或 'LINEAR_TEAM_ID': Linear团队的标识符。
- 'JIRA_SERVER': 如果使用JIRA适配器，JIRA服务器的URL（例如 'https://yourcompany.atlassian.net'）。
- 'JIRA_EMAIL': 您的JIRA账户邮箱。
- 'JIRA_API_TOKEN': 您的JIRA API令牌。
- 'GITHUB_TOKEN': 如果使用GitHub适配器，您的GitHub个人访问令牌。
- 'GITHUB_OWNER': GitHub仓库的所有者名称。
- 'GITHUB_REPO': GitHub仓库名称。
- 'AITRACKDOWN_BASE_PATH': 如果使用AI-Trackdown适配器（本地文件存储），指定票证数据文件的存储路径。
- 'PYTHONPATH': (如果您的AI客户端在不同环境中运行，并且需要MCP Ticketer模块的路径时，可能需要设置此项。) 指向您的MCP Ticketer安装路径，例如 '/path/to/mcp-ticketer/src'。

示例 MCP 客户端配置结构（通常由AI客户端自动生成或指导您填写）：

{
  "mcpServers": {
    "your-mcp-ticketer-instance-name": {
      "command": "/path/to/your/virtualenv/bin/python",
      "args": ["-m", "mcp_ticketer.mcp.server"],
      "env": {
        "MCP_TICKETER_ADAPTER": "linear",
        "LINEAR_API_KEY": "YOUR_LINEAR_API_KEY",
        "LINEAR_TEAM_KEY": "YOUR_LINEAR_TEAM_KEY"
      }
    }
  }
}

重要提示：

路径： 确保 'command' 指向您安装MCP Ticketer的正确Python可执行文件路径。
敏感信息： 'env' 中的API密钥等敏感信息，通常不直接写在客户端配置文件中，而是通过客户端的安全机制（如环境变量或秘密管理）提供。这里仅为示例说明。
自动配置： MCP Ticketer提供了便捷的 'mcp-ticketer install <client_name>' 命令，可以自动检测您的环境并为支持的AI客户端生成和保存正确的MCP服务器配置。这是强烈推荐的做法。

基本使用方法

配置完成后，您的AI客户端就可以通过MCP Ticketer与票证系统交互了。

初始化适配器： 在项目目录中初始化配置，例如使用Linear适配器：

mcp-ticketer init --adapter linear --team-url https://linear.app/your-org/team/ENG/active

或者使用本地文件存储的AI-Trackdown适配器：

mcp-ticketer init --adapter aitrackdown

（此步骤通常只需执行一次，或由 'mcp-ticketer install' 命令自动完成）

使用MCP客户端调用工具（示例，具体语法取决于您的AI客户端）：

创建任务：

# 假设您的AI客户端支持类似这样的Python工具调用
result = await ticket_create(
    title="修复登录页面Bug",
    description="用户无法通过OAuth登录",
    priority="high",
    assignee="john.doe"
)

列出任务：

result = await ticket_list(state="open", limit=10, compact=True) # 使用紧凑模式节省token

更新任务：

result = await ticket_update(ticket_id="TICKET-123", priority="critical")

添加评论：

result = await ticket_add_comment(ticket_id="TICKET-123", content="正在处理此任务，预计今天完成。")

获取自定义指令：

result = await instructions_get()
# AI客户端会接收到当前定义的票证撰写指令

通过这些功能，您的AI代理可以像人类一样高效地管理项目票证。

关键词

项目简介

主要功能点

安装步骤

服务器配置（为MCP客户端提供）

基本使用方法

信息