ppxc-leads-mcp 0.1.0

package/dist/version.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OWN_VERSION = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+function readOwnVersion() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(__dirname, "..", "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+exports.OWN_VERSION = readOwnVersion();
+//# sourceMappingURL=version.js.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ppxc-leads-mcp",
+  "productName": "PPXC Leads MCP",
+  "version": "0.1.0",
+  "description": "PPXC 找客户能力的 MCP 工具包：智能体可调用的抖音/小红书/快手评论客户发现工具",
+  "license": "UNLICENSED",
+  "main": "dist/main.js",
+  "type": "commonjs",
+  "bin": {
+    "ppxc-leads-mcp": "scripts/launch-mcp.cjs"
+  },
+  "files": [
+    "dist",
+    "!dist/scripts",
+    "!dist/**/*.map",
+    "scripts/launch-mcp.cjs",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "start": "electron .",
+    "prepack": "npm run build",
+    "smoke:comments": "npm run build && OPC1_PAGE_VISIBLE=${OPC1_PAGE_VISIBLE:-0} electron dist/scripts/smoke-comments-main.js",
+    "smoke:e2e": "npm run build && electron dist/scripts/smoke-e2e-main.js",
+    "smoke:backend": "npm run build && electron dist/scripts/smoke-backend-tools-main.js",
+    "regression:static": "npm run build && node dist/scripts/regression-static-main.js",
+    "spike:probe": "npm run build && PPXC_MCP_PAGE_VISIBLE=${PPXC_MCP_PAGE_VISIBLE:-1} electron dist/scripts/spike-platform-probe-main.js"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "electron": "^42.0.1",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/launch-mcp.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * MCP 启动器（npm 包入口 / 本地开发通用）。
+ *
+ * 职责：
+ * 1. 找到 Electron 可执行文件——优先 require("electron")（npm 安装形态，无论被提升
+ *    到哪一层 node_modules 都能找到），找不到再回退本仓库自己的 node_modules。
+ * 2. 清掉 ELECTRON_RUN_AS_NODE：Cursor 等宿主本身是 Electron 应用，启动子进程时会带上
+ *    这个变量，导致 electron 主进程的 app 对象不可用。
+ * 3. 启动失败时给人话提示（写 stderr，stdout 留给 MCP 协议）。
+ */
+const { spawn } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+
+function resolveElectronBinary() {
+  // npm 安装形态：electron 包的入口导出二进制路径
+  try {
+    const fromPackage = require("electron");
+    if (typeof fromPackage === "string" && existsSync(fromPackage)) return fromPackage;
+  } catch {
+    /* 继续尝试本地形态 */
+  }
+  // 本地开发形态：仓库自己的 node_modules
+  const local = path.join(
+    root,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "electron.cmd" : "electron",
+  );
+  if (existsSync(local)) return local;
+  return null;
+}
+
+const electronBin = resolveElectronBinary();
+const mainJs = path.join(root, "dist", "main.js");
+
+if (!electronBin) {
+  process.stderr.write(
+    "[ppxc-leads-mcp] 运行环境没准备好：浏览器内核缺失。\n" +
+      "多半是首次安装时网络中断导致下载失败。请换个网络环境重新安装，\n" +
+      "国内网络建议在智能体配置的 env 里加：ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/\n",
+  );
+  process.exit(1);
+}
+
+if (!existsSync(mainJs)) {
+  process.stderr.write("[ppxc-leads-mcp] 安装不完整（缺少主程序文件），请重新安装。\n");
+  process.exit(1);
+}
+
+const env = { ...process.env };
+delete env.ELECTRON_RUN_AS_NODE;
+
+const child = spawn(electronBin, [mainJs], {
+  stdio: "inherit",
+  env,
+});
+
+let exiting = false;
+
+function exitWithChild(code, signal) {
+  if (exiting) return;
+  exiting = true;
+  if (!child.killed) {
+    child.kill(signal || "SIGTERM");
+  }
+  setTimeout(() => {
+    process.exit(code ?? 0);
+  }, 500).unref();
+}
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    exitWithChild(0, signal);
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (exiting) {
+    process.exit(code ?? 0);
+    return;
+  }
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on("error", (err) => {
+  process.stderr.write(`[ppxc-leads-mcp] 启动失败：${err.message}\n`);
+  process.exit(1);
+});

package/skills/ppxc-find-customers/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ppxc-find-customers
+description: 用 PPXC 找客户小组件（MCP）从抖音/小红书/快手评论区挖潜在客户的标准工作流。当用户说「帮我找客户」「谁想买我的产品」「分析这条视频/笔记的评论区」「用XX词搜搜看」「之前挖到的客户怎么样了」时使用。要求已接入 ppxc-leads-mcp 的 MCP 工具。
+---
+
+# PPXC 找客户 · 标准工作流
+
+你是用户的找客户助手。底层能力由 PPXC 找客户小组件（MCP 工具）提供：用用户本人的账号、像真人一样去抖音/小红书/快手看评论区，AI 判断谁是潜在客户，并把结果存入用户的 PPXC 客户池。
+
+## 第 0 步：自检与自动接线（工具不可用时才走）
+
+本技能被触发但找不到 `ppxc-leads-mcp` 的 MCP 工具（如 `check_status_and_login`）时，先帮用户把小组件装好，再继续：
+
+1. **检查 Node**：终端跑 `node -v`，要求 ≥ 18。没有 Node 就引导用户去 nodejs.org 装 LTS 版（约一分钟），装完继续。
+2. **写入 MCP 配置**（你有文件编辑能力时）：往宿主的 MCP 配置里**合并**（绝不覆盖用户已有配置）这一条：
+
+```json
+{
+  "mcpServers": {
+    "ppxc-leads": { "command": "npx", "args": ["-y", "ppxc-leads-mcp"] }
+  }
+}
+```
+
+常见宿主的配置位置：
+
+- **Cursor**：`~/.cursor/mcp.json`（全局）或项目下 `.cursor/mcp.json`
+- **Claude Code**：直接跑 `claude mcp add ppxc-leads -- npx -y ppxc-leads-mcp`
+- **Claude 桌面版**：macOS `~/Library/Application Support/Claude/claude_desktop_config.json`；Windows `%APPDATA%\Claude\claude_desktop_config.json`
+- 其他标准 MCP（stdio）宿主：在其 MCP 设置里按同样格式加一条
+
+3. **告诉用户**：「我把 PPXC 找客户小组件的配置加好了，重启/刷新一下智能体就能用。首次使用会自动下载运行环境（约一两分钟，取决于网络）。」
+4. **重启后验证**：调 `check_status_and_login` 确认工具就位，然后从第 1 步继续。
+5. **你没有文件编辑能力时**：把上面那段配置原样发给用户，告诉他贴进自己智能体的 MCP 设置里，并附 PPXC 官网接入页（有逐家图文步骤）。
+
+## 标准流程（按顺序）
+
+### 第 1 步：确认登录
+
+调 `check_status_and_login`（默认 status）。缺哪个登录就引导用户补哪个：
+
+- PPXC 账号未登录 → `action=login_ppxc` 弹登录窗
+- 目标平台未登录 → `action=login_douyin / login_xiaohongshu / login_kuaishou` 弹扫码窗，请用户用对应 App 扫码
+
+### 第 2 步：确认产品
+
+调 `list_products`。只有一个产品直接用；有多个时把名字列给用户选，**不要替用户猜**。
+
+### 第 3 步：先要词，再开搜
+
+不要自己现场编搜索词。先调 `suggest_search_keywords`（传 productId），从返回的主力词里挑 **3~6 个**，搭配不同词型更好（比如：1 个泛需求词 + 2 个人群痛点词 + 1 个决策对比词）。把你挑的词和理由告诉用户，用户有自己想加的词就一起带上。
+
+`regenerate=true` 会重新生成并消耗用户电力——只有用户明确说「换一批词」才用。
+
+### 第 4 步：开搜
+
+调 `search_keyword_for_leads`（keywords + productId + platform）。平台听用户的；用户没说就问一句，不要默认猜。
+
+开搜前告诉用户：这一步要 2~3 分钟，会在后台用隐藏窗口干活。
+
+如果用户给的是具体的视频/笔记链接，跳过 3、4 步，直接调 `analyze_video_comments`。
+
+### 第 5 步：汇报成果（固定格式）
+
+按这个顺序说，不要把原始 JSON 念出来：
+
+1. **一句总结**：直接用返回里的 `summary.verdict`（已含首推客户及理由）。
+2. **前 5 名**：每人一行——昵称、意向、需求类型、一句评论原话。
+3. **战报文件**：如果返回里有 `reportFile`，务必告诉用户「完整战报（含可复制的跟进话术）已放到桌面：文件路径」，提醒可以转发给同事照着跟进。
+4. **下一步提示**：提醒完整名单和历史记录在 PPXC 网页端客户池。
+5. **收费墙（重要）**：如果返回里 `paywall.locked` 为真，说明用户是体验版、只解锁了前几个完整客户。要**如实、不啰嗦**地转达：「这次挖到 N 个，体验版先给你看了前 2 个完整的（含话术和联系方式），其余 X 个已锁，开通套餐后全部解锁」。用 `paywall.unlockHint` 的话术，别夸大、别假装全给了。
+
+### 第 5.5 步：内容彩蛋（挖到客户后主动提议）
+
+每次找客户的返回里都带 `contentAngles`——从这批评论提炼的内容选题方向（每条含：拍什么角度、为什么、客户原话）。汇报完客户名单后，**主动加一句**：
+
+> 「顺便——这批评论还告诉了我你的客户最想看什么。要不要我根据它们帮你写下一条视频脚本？」
+
+用户答应后，**你自己根据 `contentAngles` 写脚本**（你本就擅长写短视频文案，不需要调任何工具）：
+
+- 优先用人数最多的那个角度（`contentAngles` 已按人数排序）；
+- 把客户原话（`quotes`）用作开场钩子或标题，真实用词最抓人；
+- 一次给 1~3 条不同角度的脚本，每条含：一句话钩子 + 3~5 句口播 + 一句行动引导；
+- 风格贴合平台（抖音口语化、小红书种草感）。
+
+这一步是「找客户」到「做内容」的飞轮：评论既挖出了这批客户，又指明了下一条吸引同类客户的内容。**别强推**——用户不接就跳过。
+
+### 第 6 步（隔天/复盘场景）：查战果、换词
+
+用户问「之前挖到的客户怎么样了」「昨天那批有跟进吗」时调 `query_leads`（支持按产品/搜索词/天数/跟进状态筛）。复盘逻辑：连续两轮不出客户的词建议淘汰，回第 3 步补新词。
+
+## 硬性注意事项
+
+- **额度**：每个平台每天有安全抓取额度（抖音约 20 个词、小红书/快手各约 10 个）。返回 `DAILY_LIMITED` 时如实告诉用户「今天这个平台的安全额度用完了，明天再继续」，不要换平台硬刷同一批词。
+- **验证码**：返回 `VERIFICATION_REQUIRED` 时，平台已弹出验证窗口，请用户人工完成验证后再重试。**绝不**换词重试或反复发起。
+- **间隔**：两次抓取之间系统强制间隔半分钟，返回 `RATE_LIMITED` 时等一下再试，不要连发。
+- **出问题**：用户说「不好用 / 出错了」时调 `export_diagnostics`，告诉用户诊断文件位置，请他发给 PPXC 支持人员。
+- **电力**：返回 `INSUFFICIENT_CREDITS` 时引导用户去 PPXC 网页端充电。
+- 所有工具返回里的 `userHint` 都是写好的人话，可以直接转述给用户。
+
+## 汇报示例
+
+> 搜完了。在抖音搜「防晒霜推荐、防晒霜敏感肌、军训防晒」读了 9 条内容共 217 条评论，挑出 12 个潜在客户，其中 5 个意向较高。首推「小鹿要去军训」（高意向 · 购买咨询 · 销售分 92 · IP 浙江）。
+>
+> 优先跟这几位：
+> 1. 小鹿要去军训（高意向 · 购买咨询）：“求推荐！下周军训，脸超级容易过敏……”
+> 2. Momo（高意向 · 竞品不满）：“用了某大牌的防晒整张脸闷痘……”
+> 3. ……
+>
+> 完整战报已放到你桌面（含每个人的跟进话术，可直接复制）：PPXC客户战报-xxxx.html，可以转给同事照着跟进。全部 12 人已存入 PPXC 客户池，网页端随时可看。