麦克普蒂克斯
一个简单、强大的票务跟踪系统，集成了 AI 助手。
mcptix 是什么？
mcptix 是一个工单跟踪系统，可帮助您管理项目的任务、错误和功能。它设计简单易用，并通过模型上下文协议 (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（Claude Desktop、Roo等）的AI助手
步骤1：安装mcptix
npm install @ownlytics/mcptix
第 2 步：在你的项目中初始化 mcptix
这将：
- 在你的项目中创建一个
.mcptix文件夹 - 添加配置文件
- 设置数据库结构
步骤 3：启动 mcptix UI
这将仅启动 mcptix UI（API 服务器）。MCP 服务器将在需要时由您的 AI 助手启动。
AI集成指南
mcptix 最强大的功能之一是通过模型上下文协议 (MCP) 与 AI 助手集成。这使得 AI 助手能够帮助进行项目规划、任务分解等。
了解 mcptix AI 集成
正确配置后，mcptix 可使您的 AI 助手执行以下操作：
- 创建、读取、更新和删除票证
- 向票证添加评论
- 在
agent_context字段中存储详细的计划信息 - 将复杂的任务分解为可管理的工单
- 跟踪复杂性指标
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
- 复制 MCP 配置：运行
npx mcptix init时，会在.mcptix/mcp-server-config.json处创建一个 MCP 服务器配置文件。将其复制到 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桌面：在 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。
- 在 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 UI ：
- 与 Claude Desktop 或您的 AI 助手展开对话，规划您的项目
- 寻求帮助分解复杂任务：例如：“我需要实施用户身份验证系统。您能帮我将其分解为可管理的票证吗？”
- AI 将在
agent_context字段中创建包含详细计划的工单 - 在 mcptix UI 中**查看票证，**网址为http://localhost:3000 （或您配置的端口）
- 按照
agent_context字段中的计划执行工单 - 与您的 AI 助手一起审查进度并根据需要完善计划
与 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.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 时出现“未找到命令”
- 确保你已经安装了 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 提供了几个命令行选项：
# 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
📄查看完整许可条款
尊重此许可有助于支持持续发展和创新。