麦克普蒂克斯

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

mcptix 是什么？

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

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

快速入门指南

对于那些想要快速掌握并运行基本功能的用户：

基本用法就是这样！关于AI助手集成，请参阅下方的AI集成指南。

完整安装指南

先决条件

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

步骤1：安装mcptix

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

这将：

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

步骤 3：启动 mcptix UI

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

AI集成指南

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

了解 mcptix AI 集成

正确配置后，mcptix 可使您的 AI 助手执行以下操作：

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

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

💡⚡️ 使用 mcptix 实现经济高效的开发

让一个通过 API 连接的 LLM 代理持续规划、执行代码、处理错误和调试，很快就会变得成本高昂。当您的代理需要重复处理相同的上下文并在交互过程中维护状态时，API 成本就会累积起来。

**更经济实惠的方法：**使用运行 Claude 3.7 Sonnet 的专业版账户配置 Claude Desktop，并启用 mcptix 和文件系统访问权限。这种本地设置可以显著减少 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的结果）。

对于克劳德桌面

1. 如果尚未安装，请安装桌面指挥官：
   npm install -g @wonderwhy-er/desktop-commander
2. 将 Claude Desktop 连接到您的文件系统：
   desktop-commander connect
3. 配置Claude桌面：在 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. 编辑项目系统说明：为 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 助手讨论您的项目了。工作流程如下：

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. 告诉助理找票：
   Find tickets in the 'in-progress' status.
2. 要求助理处理特定工单：
   Work on ticket id `ticket-1234567890` following the plan in the agent_context.
3. 助手将执行 agent_context 字段中的计划

看板使用

看板

当你打开 mcptix 时，你会看到一个看板，其中有不同票证状态的列：

• 待办事项- 需要处理的工单
• 接下来- 准备处理的工单
• 进行中- 当前正在处理的工单
• 审核中- 正在审核的工单
• 已完成- 已完成的票

手动创建工单

1. 点击右上角的“新票”按钮
2. 填写票证详细信息：
   • 标题
   • 描述
   • 地位
   • 优先事项
3. 点击“保存”

更新工单

1. 单击票证即可打开它
2. 编辑票证详细信息
3. 更改会自动保存

添加评论

1. 开立票据
2. 向下滚动到评论部分
3. 输入您的评论
4. 点击“添加评论”

高级配置

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

常见自定义

• 更改端口：如果端口 3000 已被使用，请将apiPort更改为其他数字
• 更改数据位置：如果要将数据存储在其他地方，请更改dbPath

故障排除

安装问题

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

mcptix UI 无法启动

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

人工智能集成问题

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

命令行参考

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

了解 MCP 架构

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

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

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

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

🛡️ 许可与使用

该项目根据**商业源许可证 1.1（BSL 1.1）**获得许可。

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

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

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

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

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