麦普提克斯

Name: 麦普提克斯
Author: ownlytics

作者：ownlytics6 星标更新：2025-04-10

安装使用来源：spider==github.com

项目介绍

mcptix

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

mcptix Banner

mcptix 是什么？

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

📋 跟踪票务 - 创建、更新和管理项目中的票务
🧠 衡量复杂性 - 使用复杂性智能引擎追踪票务的复杂度
💬 添加评论 - 在票务上协作并添加评论
🤖 AI 集成 - 将您的AI助手连接到mcptix以增强规划和编码

快速入门指南

对于希望快速启动基本功能的人来说：

# 安装 mcptix
npm install @ownlytics/mcptix

# 在项目中初始化 mcptix
npx mcptix init

# 启动 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 最强大的特性之一是通过模型上下文协议（MCP）与AI助手集成。这允许AI助手帮助进行项目规划、任务分解等。

理解 mcptix 的AI集成

当正确配置后，mcptix 可以让您的AI助手：

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

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

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

拥有一个API连接的LLM代理持续地进行规划、执行代码、处理错误和调试可能会迅速变得昂贵。当您的代理需要反复处理相同上下文并在交互之间维持状态时，API费用会累积起来。

更经济的方法：配置Claude Desktop（带有Pro账户运行Claude 3.7 Sonnet）与mcptix和文件系统访问。这种本地设置显著减少了API使用量，同时保持了强大的AI辅助。

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

mcptix充当下一代LLM编码代理的记忆库，使它们能够将详细规划和上下文卸载到持久存储系统中，以便按需引用，而不是将其全部保留在有限的上下文窗口内。

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

不同AI助手的配置

对于Roo

复制MCP配置：

当您运行 npx mcptix init 时，会在 .mcptix 目录下创建一个 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 的结果）。

对于Claude Desktop

如果尚未安装，请安装 desktop-commander：
```
npm install -g @wonderwhy-er/desktop-commander
```
连接 Claude Desktop 到您的文件系统：
```
desktop-commander connect
```

配置 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。

在 Claude Desktop 中创建项目：
- 在 Claude Desktop 中点击“新建项目”
- 给项目命名
- 将项目目录设置为您开发项目的根目录

编辑项目系统指令：

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

该项目使用 mcptix 进行票务跟踪。在规划工作时：

1. 使用 mcptix MCP 服务器创建和管理票务
2. 将复杂的任务分解成较小的票务
3. 使用票务中的 agent_context 字段存储全面的规划，格式为 Markdown
4. 项目文件位于：/path/to/your/project

使用 mcptix 与AI助手

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

启动 mcptix UI：
```
npx mcptix start
```
与 Claude Desktop 或您的AI助手开始对话，讨论项目规划
请求帮助分解复杂任务：示例：“我需要实现用户认证系统。你能帮我将其分解成可管理的票务吗？”
AI将创建票务，在 agent_context 字段中包含详细的规划
在 mcptix UI 中查看票务，地址为 http://localhost:3000（或您配置的端口）
根据 agent_context 字段中的计划执行票务
与您的AI助手一起审查进度，并根据需要调整计划

使用 Cline/Roo

当与 Cline 或 Roo 工作时：

告诉助手查找票务：

查找状态为 '正在进行' 的票务。

要求助手处理特定票务：

处理票务 id `ticket-1234567890`，按照 agent_context 中的计划进行。

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

看板使用

看板

打开 mcptix 后，您会看到一个看板，列出了不同票务状态的列：

待办事项 - 需要处理的票务
即将开始 - 准备开始处理的票务
正在进行 - 正在处理的票务
待审核 - 正在审核的票务
已完成 - 已完成的票务

手动创建票务

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

更新票务

点击票务以打开它
编辑票务详情
更改会自动保存

添加评论

打开票务
滚动到底部的评论部分
输入您的评论
点击“添加评论”

高级配置

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

module.exports = {
  // 数据库配置
  dbPath: './.mcptix/data/mcptix.db',

  // API 服务器配置
  apiPort: 3000,
  apiHost: 'localhost',

  // 服务器选项
  mcpEnabled: false, // 默认禁用 - MCP 服务器应由 LLM 代理启动
  apiEnabled: true,

  // 日志配置
  logLevel: 'info',

  // 数据管理
  clearDataOnInit: false,
};

常见自定义

更改端口：如果端口 3000 已被占用，将 apiPort 更改为其他数字
更改数据位置：如果您想将数据存储在其他位置，更改 dbPath

故障排除

安装问题

运行 mcptix 时出现“命令未找到”
- 确保已安装 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 助手的日志中的错误消息
“模块未找到”错误
- 确保 mcptix 已正确安装
- 检查 MCP 配置中的路径是否正确

命令行参考

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

# 在项目中初始化 mcptix
npx mcptix init

# 启动 mcptix
npx mcptix start

# 使用自定义端口和主机启动
npx mcptix start --port 3001 --host 0.0.0.0

# 启动但不打开浏览器
npx mcptix start --no-open

# 仅启动 MCP 服务器（用于开发/测试目的）
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
📄 查看完整的许可证条款

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