Name: AI集成票务跟踪系统
Author: ownlytics

使用说明

mcptix

一个简单、强大的票务跟踪系统，集成了人工智能助手。

什么是mcptix？

mcptix是一个票证跟踪系统，可帮助您管理项目的任务、错误和功能。它的设计易于使用，并通过模型上下文协议（MCP）与AI助手集成。

📋 轨道票 -为您的项目创建、更新和管理工单
🧠 衡量复杂性 -使用复杂性智能引擎跟踪您的票有多复杂
💬 添加评论 -与门票评论合作
🤖 人工智能集成 -将您的AI助手连接到mcptix，以增强规划和编码

快速入门指南

对于那些想快速启动并运行基本功能的人：

# Install mcptix
npm install @ownlytics/mcptix

# Initialize mcptix in your project
npx mcptix init

# Start mcptix
npx mcptix start

这就是基本用法！有关AI助手集成，请参阅 AI集成指南在......下面

完整安装指南

先决条件

Node.js 14或更高版本
npm或纱线
支持MCP（Claude Desktop、Roo等）的AI助手

步骤1：安装mcptix

npm install @ownlytics/mcptix

步骤2：在项目中初始化mcptix

npx mcptix init

这将：

创建一个 .mcptix 项目中的文件夹
添加配置文件
设置数据库结构

步骤3：启动mcptix用户界面

npx mcptix start

这将仅启动mcptix UI（API服务器）。MCP服务器将在需要时由您的AI助手启动。

AI集成指南

mcptix最强大的功能之一是通过模型上下文协议（MCP）与AI助手集成。这使得AI助手能够帮助进行项目规划、任务分解等。

了解mcptix AI集成

如果配置正确，mcptix将使您的AI助手能够：

创建、读取、更新和删除工单
为门票添加评论
将详细的规划信息存储在 agent_context 领域
将复杂任务分解为可管理的工单
跟踪复杂性指标

这 agent_context 该字段特别强大——它为人工智能助手提供了一个使用Markdown存储大量计划文档的地方，而不会扰乱对话。

💡⚡️ 使用mcptix进行经济高效的开发

让一个API连接的LLM代理持续规划、执行代码、处理错误和调试可能会很快变得昂贵。当代理需要重复处理相同的上下文并在交互中维护状态时，API成本会增加。

一种更具成本效益的方法： 使用mcptix和文件系统访问配置Claude Desktop（使用运行Claude 3.7 Sonnet的Pro帐户）。这种本地设置大大减少了API的使用，同时保持了强大的人工智能辅助。

通过将综合计划存储在 agent_context 将文件名、行号、方法名和其他引用点组织成逻辑的、可操作的块的field-complete，您可以将API的使用量减少80%。

mcptix充当LLM编码代理的下一代内存库，允许它们将详细的计划和上下文卸载到持久存储系统中，以便根据需要进行引用，而不是将所有内容都保存在有限的上下文窗口中。

这个系统之所以特别强大，是因为你的编码代理（如Roo/Cline）和Claude Desktop都访问相同的底层mcptix数据库。这创建了一个无缝的协作环境，Claude Desktop可以在其中创建全面的计划并将其存储在工单中，而您的编码代理可以检索这些工单并精确执行计划。它们通过共享票系统进行有效的通信——Claude Desktop将复杂的任务分解为可执行的块，您的编码代理可以实现它们，而无需每次重新生成上下文。

不同AI助手的配置

对于Roo

复制MCP配置:

当你奔跑时 npx mcptix init，在以下位置创建MCP服务器配置文件 .mcptix/mcp-server-config.json.将此复制到Roo的配置目录：
```
mkdir -p .roo
cp .mcptix/mcp-server-config.json .roo/mcp.json
```
检查配置文件 为了确保路径是绝对的：
```
{
  "mcpServers": {
    "mcptix": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/node_modules/@ownlytics/mcptix/dist/mcp/index.js"],
      "env": {
        "MCPTIX_HOME_DIR": "/absolute/path/to/your/project/.mcptix",
        "HOME": "/home/your-username"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
```
确保 /absolute/path/to/node 是跑步的结果 which node 在你的终端。

确保 /absolute/path/to/node_modules/@ownlytics/mcptix/dist/mcp/index.js 是node_modules中指向mcptix MCP服务器的绝对路径。

确保 /absolute/path/to/your/project/.mcptix 是项目的绝对路径 .mcptix 目录。

确保 /home/your-username 是您的主目录（结果 echo $HOME).

适用于克劳德桌面

安装桌面命令器 如果你还没有：

npm install -g @wonderwhy-er/desktop-commander

将Claude Desktop连接到您的文件系统:
```
desktop-commander connect
```

配置Claude桌面:

在克劳德桌面中：

前往“设置”>“开发人员”
在“MCP服务器配置”部分添加MCP配置：

{
  "mcpServers": {
    "mcptix": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/node_modules/@ownlytics/mcptix/dist/mcp/index.js"],
      "env": {
        "MCPTIX_HOME_DIR": "/absolute/path/to/your/project/.mcptix",
        "HOME": "/home/your-username"
      },
      "disabled": false,
      "alwaysAllow": []
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander", "--config", "{}"]
    }
  }
}

按照编码代理配置中的说明使用json。

在Claude Desktop中创建项目:
- 在Claude Desktop中单击“新建项目”
- 恰当地命名您的项目
- 将项目目录设置为开发项目的根目录

编辑项目系统说明:

为Claude添加有关使用mcptix的说明：

This project uses mcptix for ticket tracking. When planning work:

1. Use the mcptix MCP server to create and manage tickets
2. Break down complex tasks into smaller tickets
3. Use the agent_context field in tickets to store comprehensive planning in Markdown format
4. Project files are located in: /path/to/your/project

将mcptix与AI助手结合使用

配置后，您可以开始与您的AI助手讨论您的项目。以下是一个工作流程：

启动mcptix用户界面:
```
npx mcptix start
```
发起对话 与Claude Desktop或您的AI助手一起规划您的项目
寻求帮助分解复杂任务: 示例：“我需要实现一个用户身份验证系统。你能帮我把它分解成可管理的票证吗？”
人工智能将创建门票 详细规划 agent_context 领域
查看门票 在mcptix用户界面中http://localhost:3000（或您配置的端口）
执行门票 按照计划 agent_context 领域
审查进度 与您的人工智能助手一起，根据需要完善计划

与Cline/Roo合作

与Cline或Roo合作时：

告诉助理找票:

Find tickets in the 'in-progress' status.

让助理处理一张特定的票:

Work on ticket id `ticket-1234567890` following the plan in the agent_context.

助理将执行计划 在agent_context字段中

看板使用

看板板

当你打开mcptix时，你会看到一个看板，上面有不同工单状态的列：

待办事项 -需要处理的门票
下一个 -已准备就绪的门票
进行中 -目前正在制作的门票
审核中 -正在审核的门票
完成 -已完成的门票

手动创建工单

点击右上角的“新票”按钮
填写门票详细信息：
- 标题
- 描述
- 状态
- 优先级
点击“保存”

更新工单

点击一张票打开它
编辑工单详细信息
更改会自动保存

添加评论

打开一张票
向下滚动到评论部分
键入您的评论
点击“添加评论”

高级配置

您可以通过编辑来自定义mcptix .mcptix/mcptix.config.js 文件：

module.exports = {
  // Database configuration
  dbPath: './.mcptix/data/mcptix.db',

  // API server configuration
  apiPort: 3000,
  apiHost: 'localhost',

  // Server options
  mcpEnabled: false, // Disabled by default - MCP server should be started by the LLM agent
  apiEnabled: true,

  // Logging configuration
  logLevel: 'info',

  // Data management
  clearDataOnInit: false,
};

常见自定义

更改端口：如果端口3000已在使用中，请更改 apiPort 到另一个号码
更改数据位置：如果要将数据存储在其他地方，请更改 dbPath

故障排除

安装问题

运行mcptix时“找不到命令”
- 确保您已安装mcptix(npm install @ownlytics/mcptix)
- 尝试使用完整路径： ./node_modules/.bin/mcptix
初始化失败
- 检查您是否有权限写入当前目录
- 确保Node.js已安装并且是最新的

mcptix用户界面无法启动

端口已在使用中
- 更改端口 .mcptix/mcptix.config.js
- 检查另一个实例是否已在运行
数据库错误
- 确保数据库路径可访问
- 检查上的文件权限 .mcptix 目录

AI集成问题

AI助手无法连接到mcptix
- 验证MCP配置路径是否绝对正确
- 检查您的AI助手是否支持MCP
- 确保配置中的数据库路径可供MCP服务器访问
MCP服务器无法启动
- 检查MCP配置中的环境变量
- 验证Node.js和mcptix MCP服务器的路径
- 在AI助手的日志中查找错误消息
“找不到模块”错误
- 确保mcptix安装正确
- 检查MCP配置中的路径是否正确

命令行参考

mcptix提供了几个命令行选项：

# Initialize mcptix in your project
npx mcptix init

# Start mcptix
npx mcptix start

# Start with custom port and host
npx mcptix start --port 3001 --host 0.0.0.0

# Start without opening the browser
npx mcptix start --no-open

# Start only the MCP server (for development/testing purposes)
npx mcptix mcp

了解MCP架构

MCP（模型上下文协议）服务器旨在由您的AI助手启动，而不是由mcptix本身启动。该架构确保：

MCP服务器仅在需要时运行
MCP服务器可以访问正确的数据库
MCP服务器已为您的AI助手正确配置

当您的AI助手需要与mcptix交互时，它将：

从配置目录中读取MCP配置文件
按照配置中的指定启动MCP服务器
连接到MCP服务器
使用MCP服务器提供的工具和资源与mcptix交互

🛡️ 许可和使用

该项目根据 商业来源许可证1.1（BSL 1.1）.

欢迎您使用、修改和探索此软件 非商业性的 目的，包括内部评估、实验或研究。

商业用途，包括生产、付费服务或企业环境，需要Tesseract Labs，LLC的商业许可证。

我们很乐意为希望集成或扩展此工具的团队提供支持。请联系我们获取许可或咨询：

📧 hello@ownlytics.io
📄 查看完整的许可条款

尊重此许可证有助于支持持续的开发和创新。