mcptix

一个简单而强大的票务跟踪系统，集成了AI助手。

什么是 mcptix？

mcptix 是一个票务跟踪系统，帮助你管理项目中的任务、bug 和功能。它设计得易于使用，并通过 Model Context Protocol (MCP) 集成了 AI 助手。

• 📋 跟踪票据 - 为你的项目创建、更新和管理票据
• 🧠 衡量复杂性 - 使用复杂度智能引擎追踪票据的复杂程度
• 💬 添加评论 - 通过票据上的评论进行协作
• 🤖 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 或 yarn
• 支持 MCP 的 AI 助手（如 Claude Desktop、Roo 等）

第一步：安装 mcptix

npm install @ownlytics/mcptix

第二步：在你的项目中初始化 mcptix

npx mcptix init

这将：

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

第三步：启动 mcptix UI

npx mcptix start

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

AI 集成指南

mcptix 最强大的功能之一是通过 Model Context Protocol (MCP) 与 AI 助手集成。这使得 AI 助手能够帮助项目规划、任务分解等。

了解 mcptix AI 集成

当正确配置后，mcptix 使你的 AI 助手能够：

1. 创建、读取、更新和删除票据
2. 向票据添加评论
3. 在 agent_context 字段中存储详细的规划信息
4. 将复杂任务分解为可管理的票据
5. 跟踪复杂度指标

agent_context 字段特别强大——它为 AI 助手提供了一个地方来使用 Markdown 存储详尽的规划文档，而不会使对话变得混乱。

💡⚡️ 使用 mcptix 进行成本效益开发

拥有一个通过 API 连接的 LLM 代理持续进行计划、执行代码、处理错误和调试很快就会变得非常昂贵。当您的代理需要反复处理相同的上下文并在交互中保持状态时，API 成本会累积起来。

一种更具成本效益的方法： 使用 mcptix 和文件系统访问配置 Claude Desktop（使用运行 Claude 3.7 Sonnet 的 Pro 账户）。这种本地设置可以显著减少 API 使用量，同时保持强大的 AI 辅助功能。

通过在 agent_context 字段中存储全面的计划——包括文件名、行号、方法名和其他参考点，并将它们组织成逻辑上可操作的块——您可以将 API 使用量减少多达 80%。

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

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

针对不同 AI 助手的配置

对于 Roo

1. 复制 MCP 配置：

   当您运行 npx mcptix init 时，会在 .mcptix/mcp-server-config.json 创建一个 MCP 服务器配置文件。将其复制到 Roo 的配置目录中：

   mkdir -p .roo
   cp .mcptix/mcp-server-config.json .roo/mcp.json
   

2. 检查配置文件 以确保路径是绝对路径：

   {
     "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 的结果）。

对于 Claude Desktop

1. 安装 desktop-commander（如果尚未安装）：

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

2. 将 Claude Desktop 连接到你的文件系统：

   desktop-commander connect
   

3. 配置 Claude Desktop：

   在 Claude Desktop 中：

   • 转到设置 > 开发者
   • 在“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。

4. 在 Claude Desktop 中创建项目：

   • 在 Claude Desktop 中点击“新建项目”
   • 为项目命名
   • 将项目目录设置为你开发项目的根目录

5. 编辑项目系统说明：

   添加关于使用 mcptix 的说明给 Claude：

   该项目使用 mcptix 进行工单跟踪。在规划工作时：
   
   1. 使用 mcptix MCP 服务器来创建和管理工单
   2. 将复杂任务分解成更小的工单
   3. 在工单中的 `agent_context` 字段以 Markdown 格式存储详细的计划
   4. 项目文件位于：/path/to/your/project
   

使用 AI 助手配合 mcptix

配置完成后，你可以开始与你的 AI 助手讨论你的项目。这里是一个工作流程：

1. 启动 mcptix UI：

   npx mcptix start
   

2. 与 Claude Desktop 或你的 AI 助手发起对话，讨论如何规划你的项目

3. 请求帮助分解复杂的任务：
   示例：“我需要实现一个用户认证系统。你能帮我把这个任务分解成可管理的小工单吗？”

4. AI 会根据 agent_context 字段创建带有详细规划的工单

5. 在 mcptix UI 中查看工单，网址为 http://localhost:3000（或你配置的端口）

6. 按照 agent_context 字段中的计划执行工单

7. 与你的 AI 助手一起回顾进展，并根据需要调整计划

与 Cline/Roo 工作

当与 Cline 或 Roo 工作时：

1. 告诉助手查找工单：

   查找状态为 'in-progress' 的工单。
   

2. 让助手处理特定的工单：

   按照 `agent_context` 中的计划处理工单 id `ticket-1234567890`。
   

3. 助手将执行 agent_context 字段中的计划

看板使用指南

看板

当你打开 mcptix 时，你会看到一个看板，其中包含不同工单状态的列：

• Backlog - 需要处理的工单
• Up Next - 准备好可以开始处理的工单
• In Progress - 当前正在处理的工单
• In Review - 正在审核中的工单
• Completed - 已完成的工单

手动创建工单

1. 点击右上角的“新建工单”按钮
2. 填写工单详情：
   • 标题
   • 描述
   • 状态
   • 优先级
3. 点击“保存”

更新工单

1. 点击一个工单以打开它
2. 编辑工单详情
3. 更改会自动保存

添加评论

1. 打开工单
2. 向下滚动到评论部分
3. 输入你的评论
4. 点击“添加评论”

高级配置

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

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 时出现 "Command not found"

  • 确保你已经安装了 mcptix (npm install @ownlytics/mcptix)
  • 尝试使用完整路径：./node_modules/.bin/mcptix

• 初始化失败

  • 检查你是否有权限写入当前目录
  • 确保已安装并更新 Node.js

mcptix UI 无法启动

• 端口已被占用

  • 在 .mcptix/mcptix.config.js 中更改端口
  • 检查是否已有另一个实例在运行

• 数据库错误

  • 确保数据库路径可访问
  • 检查 .mcptix 目录的文件权限

AI 集成问题

• AI 助手无法连接到 mcptix

  • 确认 MCP 配置路径是绝对且正确的
  • 检查你的 AI 助手是否支持 MCP
  • 确保配置中的数据库路径对 MCP 服务器是可访问的

• MCP 服务器无法启动

  • 检查 MCP 配置中的环境变量
  • 确认 Node.js 和 mcptix MCP 服务器的路径
  • 查看 AI 助手日志中的错误消息

• "Module not found" 错误

  • 确保正确安装了 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（Model Context Protocol）服务器设计为由你的 AI 助手启动，而不是由 mcptix 本身启动。这种架构确保了以下几点：

1. MCP 服务器仅在需要时运行
2. MCP 服务器可以访问正确的数据库
3. MCP 服务器针对你的 AI 助手进行了适当的配置

当你的 AI 助手需要与 mcptix 交互时，它会：

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

🛡️ 许可与使用

本项目采用 Business Source License 1.1 (BSL 1.1) 许可。

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

商业用途——包括在生产环境、付费服务或企业环境中使用——需要从 Tesseract Labs, LLC 获得商业许可。

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

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

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