@camscanner/tracking-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @camscanner/tracking-mcp-server
+
+MCP Server for querying Intsig Data Studio tracking/burial point documentation.
+
+## Features
+
+- SSO authentication via browser (QR code scan)
+- List products, product types, and versions
+- Search tracking records by developer, product, keyword, PageID, ActionID
+- View tracking screenshots/attachments as images
+- Credential persistence (7-day validity)
+
+## Installation
+
+```bash
+npx -y @camscanner/tracking-mcp-server@latest
+```
+
+## MCP Configuration
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "tracking": {
+    "command": "npx",
+    "args": ["-y", "@camscanner/tracking-mcp-server@latest"],
+    "env": {
+      "TRACKING_BASE_URL": "https://bigdata.intsig.net",
+      "SSO_LOGIN_URL": "https://web-sso.intsig.net/login",
+      "SSO_PLATFORM_ID": "FEOXFe858GRbG9aLymrNDLyApKcBWtrw",
+      "SSO_REDIRECT_URL": "https://ids.intsig.net/trackManage/develop"
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `tracking-auth` | SSO login via browser |
+| `tracking-logout` | Clear credentials |
+| `list_products` | List all product names |
+| `list_product_types` | Get platform types for a product |
+| `list_product_versions` | Get version list for a product |
+| `get_developer_name` | Get current user's display name |
+| `search_tracking` | Search tracking records (paginated) |
+| `get_tracking_screenshot` | Download tracking screenshot by UUID |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+export interface SsoConfig {
+    trackingBaseUrl: string;
+    ssoLoginUrl: string;
+    ssoPlatformId: string;
+    redirectUrl: string;
+}
+export interface Credentials {
+    token: string;
+    uid: string;
+    nickName: string;
+    userName: string;
+    expiresAt: number;
+}
+export declare function loadCredentials(): Promise<Credentials | null>;
+export declare function saveCredentials(creds: Credentials): Promise<void>;
+export declare function clearCredentials(): Promise<void>;
+/**
+ * Launch browser for SSO login.
+ * The SSO redirects to ids.intsig.net/trackManage/develop?token=JWT_TOKEN
+ * We capture that JWT token and use it to call the bigdata API to get user info.
+ */
+export declare function startSsoLogin(config: SsoConfig): Promise<Credentials>;

package/dist/auth.js

@@ -0,0 +1,213 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCredentials = loadCredentials;
+exports.saveCredentials = saveCredentials;
+exports.clearCredentials = clearCredentials;
+exports.startSsoLogin = startSsoLogin;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const url_1 = require("url");
+const playwright_core_1 = require("playwright-core");
+// --- Credentials persistence ---
+const CREDS_DIR = path_1.default.join(os_1.default.homedir(), ".tracking-mcp");
+const CREDS_FILE = path_1.default.join(CREDS_DIR, "credentials.json");
+const BROWSER_DATA_DIR = path_1.default.join(CREDS_DIR, "browser-data");
+async function loadCredentials() {
+    try {
+        if (!fs_1.default.existsSync(CREDS_FILE))
+            return null;
+        const data = JSON.parse(fs_1.default.readFileSync(CREDS_FILE, "utf-8"));
+        if (data && data.expiresAt > Date.now())
+            return data;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(creds) {
+    if (!fs_1.default.existsSync(CREDS_DIR))
+        fs_1.default.mkdirSync(CREDS_DIR, { recursive: true });
+    fs_1.default.writeFileSync(CREDS_FILE, JSON.stringify(creds, null, 2));
+}
+async function clearCredentials() {
+    try {
+        fs_1.default.unlinkSync(CREDS_FILE);
+    }
+    catch { /* ignore */ }
+}
+// --- Find system Chromium installed by Playwright ---
+function findChromium() {
+    const cacheDir = path_1.default.join(os_1.default.homedir(), "Library", "Caches", "ms-playwright");
+    if (!fs_1.default.existsSync(cacheDir))
+        return undefined;
+    const dirs = fs_1.default.readdirSync(cacheDir)
+        .filter(d => d.startsWith("chromium-"))
+        .sort()
+        .reverse();
+    for (const dir of dirs) {
+        const candidates = [
+            path_1.default.join(cacheDir, dir, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            path_1.default.join(cacheDir, dir, "chrome-mac", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            path_1.default.join(cacheDir, dir, "chrome-mac-arm64", "Chromium.app", "Contents", "MacOS", "Chromium"),
+            path_1.default.join(cacheDir, dir, "chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium"),
+            path_1.default.join(cacheDir, dir, "chrome-linux", "chrome"),
+        ];
+        for (const c of candidates) {
+            if (fs_1.default.existsSync(c))
+                return c;
+        }
+    }
+    return undefined;
+}
+/**
+ * Launch browser for SSO login.
+ * The SSO redirects to ids.intsig.net/trackManage/develop?token=JWT_TOKEN
+ * We capture that JWT token and use it to call the bigdata API to get user info.
+ */
+async function startSsoLogin(config) {
+    const execPath = findChromium();
+    if (!execPath) {
+        throw new Error("Cannot find Chromium. Please install Playwright browsers: npx playwright install chromium");
+    }
+    if (!fs_1.default.existsSync(BROWSER_DATA_DIR))
+        fs_1.default.mkdirSync(BROWSER_DATA_DIR, { recursive: true });
+    const ssoUrl = `${config.ssoLoginUrl}?platform_id=${config.ssoPlatformId}&redirect=${encodeURIComponent(config.redirectUrl)}&isLoginOut=1`;
+    console.error("[Auth] Launching browser for SSO login...");
+    const context = await playwright_core_1.chromium.launchPersistentContext(BROWSER_DATA_DIR, {
+        headless: false,
+        executablePath: execPath,
+        ignoreHTTPSErrors: true,
+    });
+    try {
+        const page = context.pages()[0] || await context.newPage();
+        const tokenPromise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => reject(new Error("SSO login timed out (180s)")), 180000);
+            // Watch for redirect to trackManage with token param
+            page.on("framenavigated", (frame) => {
+                if (frame !== page.mainFrame())
+                    return;
+                const url = frame.url();
+                if (url.includes("trackManage") && url.includes("token=")) {
+                    try {
+                        const parsed = new url_1.URL(url);
+                        const token = parsed.searchParams.get("token");
+                        if (token) {
+                            clearTimeout(timeout);
+                            resolve(token);
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+            });
+            // Also monitor URL changes via response
+            page.on("response", (response) => {
+                const url = response.url();
+                if (url.includes("trackManage") && url.includes("token=")) {
+                    try {
+                        const parsed = new url_1.URL(url);
+                        const token = parsed.searchParams.get("token");
+                        if (token) {
+                            clearTimeout(timeout);
+                            resolve(token);
+                        }
+                    }
+                    catch { /* ignore */ }
+                }
+            });
+        });
+        await page.goto(ssoUrl, { waitUntil: "domcontentloaded", timeout: 15000 });
+        // Check if already logged in (redirected directly with token)
+        const currentUrl = page.url();
+        if (currentUrl.includes("trackManage") && currentUrl.includes("token=")) {
+            const parsed = new url_1.URL(currentUrl);
+            const token = parsed.searchParams.get("token");
+            if (token) {
+                console.error("[Auth] Already logged in, extracting token...");
+                const creds = await exchangeToken(config.trackingBaseUrl, token);
+                await context.close();
+                return creds;
+            }
+        }
+        console.error("[Auth] Waiting for user to complete SSO login (up to 180s)...");
+        const token = await tokenPromise;
+        console.error("[Auth] Token captured, fetching user info...");
+        const creds = await exchangeToken(config.trackingBaseUrl, token);
+        console.error("[Auth] Authentication successful!");
+        return creds;
+    }
+    finally {
+        await context.close();
+    }
+}
+/** Decode JWT payload without verification to extract the sub (uid) claim */
+function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new Error("Invalid JWT format");
+    const payload = Buffer.from(parts[1], "base64url").toString("utf-8");
+    return JSON.parse(payload);
+}
+/**
+ * Use the JWT token to call the SSO login API and get user info (nickName, uid, etc.)
+ */
+function exchangeToken(baseUrl, token) {
+    return new Promise((resolve, reject) => {
+        // Decode JWT to get uid (sub field) — required as query param
+        let uid;
+        try {
+            const payload = decodeJwtPayload(token);
+            uid = payload.sub;
+            if (!uid)
+                throw new Error("No sub field in JWT");
+        }
+        catch (err) {
+            reject(new Error(`Failed to decode JWT: ${err.message}`));
+            return;
+        }
+        // Call: GET /api/bigdata/component/auth/sso/login?u={uid} with x-token header
+        const url = new url_1.URL(`${baseUrl}/api/bigdata/component/auth/sso/login?u=${uid}`);
+        const mod = url.protocol === "https:" ? https_1.default : http_1.default;
+        const options = {
+            timeout: 10000,
+            headers: {
+                "x-token": token,
+                "Accept": "application/json",
+            },
+        };
+        const req = mod.get(url.toString(), options, (res) => {
+            let body = "";
+            res.on("data", (chunk) => (body += chunk));
+            res.on("end", () => {
+                try {
+                    const data = JSON.parse(body);
+                    if (data.code !== 0 || !data.data) {
+                        reject(new Error(`SSO login API failed: ${data.msg || body.substring(0, 200)}`));
+                        return;
+                    }
+                    resolve({
+                        token,
+                        uid: data.data.uid,
+                        nickName: data.data.nickName,
+                        userName: data.data.userName,
+                        expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000,
+                    });
+                }
+                catch {
+                    reject(new Error(`Invalid JSON from SSO login: ${body.substring(0, 200)}`));
+                }
+            });
+        });
+        req.on("error", reject);
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("SSO login request timed out"));
+        });
+    });
+}

package/dist/formatters.d.ts

@@ -0,0 +1,10 @@
+/** Format product names list */
+export declare function formatProductNames(data: string[]): string;
+/** Format product types */
+export declare function formatProductTypes(data: any[]): string;
+/** Format product versions */
+export declare function formatProductVersions(data: any[]): string;
+/** Format a single tracking record */
+export declare function formatTrackingRecord(record: any): string;
+/** Format tracking list response */
+export declare function formatTrackingList(data: any): string;

package/dist/formatters.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatProductNames = formatProductNames;
+exports.formatProductTypes = formatProductTypes;
+exports.formatProductVersions = formatProductVersions;
+exports.formatTrackingRecord = formatTrackingRecord;
+exports.formatTrackingList = formatTrackingList;
+/** Format product names list */
+function formatProductNames(data) {
+    if (!Array.isArray(data) || data.length === 0)
+        return "No products found.";
+    return `Products (${data.length})\n\n${data.map((name, i) => `${i + 1}. ${name}`).join("\n")}`;
+}
+/** Format product types */
+function formatProductTypes(data) {
+    if (!Array.isArray(data) || data.length === 0)
+        return "No product types found.";
+    return `Product Types\n\n${data.map((item) => `- ${typeof item === "string" ? item : JSON.stringify(item)}`).join("\n")}`;
+}
+/** Format product versions */
+function formatProductVersions(data) {
+    if (!Array.isArray(data) || data.length === 0)
+        return "No versions found.";
+    return `Versions (${data.length})\n\n${data.map((v) => `- ${typeof v === "string" ? v : JSON.stringify(v)}`).join("\n")}`;
+}
+/** Format a single tracking record */
+function formatTrackingRecord(record) {
+    const lines = [];
+    lines.push(`${record.pageIdZh || record.pageId || "Unknown"} — ${record.actionIdZh || record.actionId || "(no action)"}`);
+    lines.push(`- ID: ${record.id}`);
+    lines.push(`- Product: ${record.product || "?"}`);
+    lines.push(`- Platform: ${record.reportPlatform || "?"} / ${record.devPlatform || "?"}`);
+    lines.push(`- Type: ${record.operation || "?"}`);
+    lines.push(`- PageID: ${record.pageId || "—"} (${record.pageIdZh || "—"})`);
+    if (record.actionId)
+        lines.push(`- ActionID: ${record.actionId} (${record.actionIdZh || "—"})`);
+    if (record.traceId)
+        lines.push(`- TraceID: ${record.traceId} (${record.traceIdZh || "—"})`);
+    if (record.description)
+        lines.push(`- Description: ${record.description}`);
+    lines.push(`- Created: ${record.createTime || "?"} by ${record.createBy || "?"}`);
+    lines.push(`- Updated: ${record.updateTime || "?"} by ${record.updateBy || "?"}`);
+    if (record.reportCount != null)
+        lines.push(`- Report Count: ${record.reportCount}`);
+    if (record.usageCount != null)
+        lines.push(`- Usage Count: ${record.usageCount}`);
+    if (record.attchUuid)
+        lines.push(`- Attachment UUID: ${record.attchUuid}`);
+    // Format attributes
+    if (record.attributes && record.attributes.length > 0) {
+        lines.push(`\nAttributes (${record.attributes.length})`);
+        for (const attr of record.attributes) {
+            lines.push(`\n${attr.extKey}: ${attr.extValue}`);
+            if (attr.extKeyDesc)
+                lines.push(`  - Key Desc: ${attr.extKeyDesc}`);
+            if (attr.extValueDesc)
+                lines.push(`  - Value Desc: ${attr.extValueDesc}`);
+            if (attr.extKeyType)
+                lines.push(`  - Type: ${attr.extKeyType}`);
+            if (attr.tag)
+                lines.push(`  - Tag: ${attr.tag}`);
+            if (attr.tapd)
+                lines.push(`  - TAPD: ${attr.tapd}`);
+            if (attr.proVersion)
+                lines.push(`  - Version: ${attr.proVersion}`);
+            if (attr.developer)
+                lines.push(`  - Developer: ${attr.developer}`);
+            if (attr.tester)
+                lines.push(`  - Tester: ${attr.tester}`);
+            const statusLabel = getStatusLabel(attr.statusCode);
+            lines.push(`  - Status: ${statusLabel} (${attr.statusCode})`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Format tracking list response */
+function formatTrackingList(data) {
+    if (!data)
+        return "No data returned.";
+    const total = data.total || 0;
+    const pageNum = data.pageNum || 1;
+    const pageSize = data.pageSize || 50;
+    const pages = data.pages || 1;
+    const records = data.data || [];
+    const lines = [];
+    lines.push(`Tracking List (Total: ${total}, Page: ${pageNum}/${pages})\n`);
+    if (records.length === 0) {
+        lines.push("No tracking records found.");
+        return lines.join("\n");
+    }
+    for (const record of records) {
+        lines.push(formatTrackingRecord(record));
+        lines.push("\n---\n");
+    }
+    return lines.join("\n");
+}
+function getStatusLabel(code) {
+    switch (code) {
+        case 0: return "Draft";
+        case 5: return "Pending Review";
+        case 10: return "Approved";
+        case 20: return "Rejected";
+        case 30: return "Deprecated";
+        default: return "Unknown";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const v3_1 = require("zod/v3");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const tracking_client_js_1 = require("./tracking-client.js");
+const auth_js_1 = require("./auth.js");
+const formatters_js_1 = require("./formatters.js");
+// --- Config from env ---
+const TRACKING_BASE_URL = process.env.TRACKING_BASE_URL || "https://bigdata.intsig.net";
+const SSO_LOGIN_URL = process.env.SSO_LOGIN_URL || "https://web-sso.intsig.net/login";
+const SSO_PLATFORM_ID = process.env.SSO_PLATFORM_ID || "FEOXFe858GRbG9aLymrNDLyApKcBWtrw";
+const SSO_REDIRECT_URL = process.env.SSO_REDIRECT_URL || "https://ids.intsig.net/trackManage/develop";
+const ssoConfig = {
+    trackingBaseUrl: TRACKING_BASE_URL,
+    ssoLoginUrl: SSO_LOGIN_URL,
+    ssoPlatformId: SSO_PLATFORM_ID,
+    redirectUrl: SSO_REDIRECT_URL,
+};
+const client = new tracking_client_js_1.TrackingClient(TRACKING_BASE_URL);
+// --- Helper: check auth before API call ---
+async function requireAuth() {
+    if (!client.isAuthenticated()) {
+        const savedCreds = await (0, auth_js_1.loadCredentials)();
+        if (savedCreds) {
+            client.setCredentials(savedCreds);
+            console.error("Restored saved credentials (valid until " + new Date(savedCreds.expiresAt).toLocaleString() + ")");
+        }
+    }
+    if (!client.isAuthenticated()) {
+        return "Not authenticated. Please call the 'tracking-auth' tool first to login via SSO.";
+    }
+    return null;
+}
+// --- MCP Server ---
+const server = new mcp_js_1.McpServer({
+    name: "tracking",
+    version: "1.0.0",
+});
+// Tool: tracking-auth
+server.tool("tracking-auth", "Login to Intsig Data Studio (tracking platform) via SSO. Opens browser for authentication.", {}, async () => {
+    if (client.isAuthenticated()) {
+        const creds = client.getCredentials();
+        return { content: [{ type: "text", text: `Already authenticated as ${creds?.nickName} (${creds?.userName}). Use 'tracking-logout' to re-authenticate.` }] };
+    }
+    try {
+        const creds = await (0, auth_js_1.startSsoLogin)(ssoConfig);
+        client.setCredentials(creds);
+        await (0, auth_js_1.saveCredentials)(creds);
+        return { content: [{ type: "text", text: `Authentication successful! Logged in as ${creds.nickName} (${creds.userName}).` }] };
+    }
+    catch (err) {
+        if (err.message?.includes("pre-verification")) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "SSO pre-verification completed. Please call 'tracking-auth' again to complete authentication.",
+                    }],
+            };
+        }
+        return { content: [{ type: "text", text: `Authentication failed: ${err.message}` }] };
+    }
+});
+// Tool: tracking-logout
+server.tool("tracking-logout", "Clear saved tracking platform credentials and logout.", {}, async () => {
+    await (0, auth_js_1.clearCredentials)();
+    client.setCredentials(null);
+    return { content: [{ type: "text", text: "Logged out. Call 'tracking-auth' to login again." }] };
+});
+// Tool: list_products
+server.tool("list_products", "List all available product names in the tracking platform", {}, async () => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const res = await client.getProductNames();
+    if (res.code !== 0) {
+        return { content: [{ type: "text", text: `Error: ${res.msg}` }] };
+    }
+    return { content: [{ type: "text", text: (0, formatters_js_1.formatProductNames)(res.data) }] };
+});
+// Tool: list_product_types
+server.tool("list_product_types", "List platform types (e.g. iOS, Android, Web) for a specific product", {
+    product_name: v3_1.z.string().describe("Product name (from list_products)"),
+}, async ({ product_name }) => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const res = await client.getProductTypes(product_name);
+    if (res.code !== 0) {
+        return { content: [{ type: "text", text: `Error: ${res.msg}` }] };
+    }
+    return { content: [{ type: "text", text: (0, formatters_js_1.formatProductTypes)(res.data) }] };
+});
+// Tool: list_product_versions
+server.tool("list_product_versions", "List available versions for a product", {
+    product_name: v3_1.z.string().describe("Product name"),
+    product_type: v3_1.z.string().optional().describe("Platform type filter (e.g. iOS, Android, Web)"),
+}, async ({ product_name, product_type }) => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const res = await client.getProductVersions(product_name, product_type || "");
+    if (res.code !== 0) {
+        return { content: [{ type: "text", text: `Error: ${res.msg}` }] };
+    }
+    return { content: [{ type: "text", text: (0, formatters_js_1.formatProductVersions)(res.data) }] };
+});
+// Tool: get_developer_name
+server.tool("get_developer_name", "Get the current logged-in developer's display name (nickName), used for querying tracking list", {}, async () => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const creds = client.getCredentials();
+    return {
+        content: [{
+                type: "text",
+                text: `Developer: ${creds?.nickName} (${creds?.userName})\nUse the nickName "${creds?.nickName}" as the developer parameter when querying tracking list.`,
+            }],
+    };
+});
+// Tool: search_tracking
+server.tool("search_tracking", "Search tracking/burial point records by developer name and product. Returns paginated list with details including PageID, ActionID, attributes, and status.", {
+    developer: v3_1.z.string().describe("Developer display name (nickName, e.g. '吴钰杰'). Use get_developer_name to get your own name."),
+    product: v3_1.z.string().describe("Product name (e.g. '扫描全能王'). Use list_products to see available products."),
+    keyword: v3_1.z.string().optional().describe("Search keyword to filter by pageId/actionId/description"),
+    page_id: v3_1.z.string().optional().describe("Filter by specific PageID"),
+    action_id: v3_1.z.string().optional().describe("Filter by specific ActionID"),
+    base_keyword: v3_1.z.string().optional().describe("Filter by base tracking keyword"),
+    attr_keyword: v3_1.z.string().optional().describe("Filter by attribute keyword"),
+    page_num: v3_1.z.number().optional().describe("Page number (default: 1)"),
+    page_size: v3_1.z.number().optional().describe("Page size (default: 50)"),
+}, async ({ developer, product, keyword, page_id, action_id, base_keyword, attr_keyword, page_num, page_size }) => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const res = await client.getTrackingList({
+        developer,
+        product,
+        keyWord: keyword,
+        pageId: page_id,
+        actionId: action_id,
+        baseKeyword: base_keyword,
+        attrKeyword: attr_keyword,
+        pageNum: page_num,
+        pageSize: page_size,
+    });
+    if (res.code !== 0) {
+        return { content: [{ type: "text", text: `Error: ${res.msg}` }] };
+    }
+    return { content: [{ type: "text", text: (0, formatters_js_1.formatTrackingList)(res.data) }] };
+});
+// Tool: get_tracking_screenshot
+server.tool("get_tracking_screenshot", "Get the screenshot/attachment image for a tracking record. Saves the image to a temp file and returns the file path for viewing.", {
+    attach_uuid: v3_1.z.string().describe("Attachment UUID from the tracking record's attchUuid field"),
+}, async ({ attach_uuid }) => {
+    const authErr = await requireAuth();
+    if (authErr)
+        return { content: [{ type: "text", text: authErr }] };
+    const result = await client.downloadFile(attach_uuid);
+    if (!result) {
+        return { content: [{ type: "text", text: "Failed to download screenshot. The attachment may not exist or the UUID is invalid." }] };
+    }
+    // 保存图片到临时文件，避免 base64 数据污染上下文
+    const ext = result.contentType.includes("png") ? ".png" : result.contentType.includes("jpeg") || result.contentType.includes("jpg") ? ".jpg" : ".png";
+    const tmpDir = path_1.default.join(os_1.default.tmpdir(), "tracking-mcp-screenshots");
+    fs_1.default.mkdirSync(tmpDir, { recursive: true });
+    const filePath = path_1.default.join(tmpDir, `${attach_uuid}${ext}`);
+    fs_1.default.writeFileSync(filePath, Buffer.from(result.base64, "base64"));
+    return {
+        content: [{
+                type: "text",
+                text: `Screenshot saved to: ${filePath}\nUse the Read tool to view this image file.`,
+            }],
+    };
+});
+// --- Start ---
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Tracking MCP Server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/tracking-client.d.ts

@@ -0,0 +1,48 @@
+import type { Credentials } from "./auth.js";
+export interface TrackingResponse<T = any> {
+    code: number;
+    msg: string;
+    data: T;
+}
+export declare class TrackingClient {
+    private baseUrl;
+    private credentials;
+    constructor(baseUrl: string);
+    setCredentials(creds: Credentials): void;
+    isAuthenticated(): boolean;
+    getCredentials(): Credentials | null;
+    private getOnce;
+    private get;
+    private postOnce;
+    private post;
+    /**
+     * Download a file/image as base64.
+     * Returns { base64, contentType } or null if failed.
+     */
+    downloadFile(uuid: string): Promise<{
+        base64: string;
+        contentType: string;
+    } | null>;
+    /** Get user nicknames list */
+    getUserNickNames(): Promise<TrackingResponse>;
+    /** Get product names list */
+    getProductNames(): Promise<TrackingResponse>;
+    /** Get product types for a product */
+    getProductTypes(productName: string): Promise<TrackingResponse>;
+    /** Get product versions */
+    getProductVersions(productName: string, productType?: string): Promise<TrackingResponse>;
+    /** Get tracking list (paginated) */
+    getTrackingList(params: {
+        developer: string;
+        product: string;
+        keyWord?: string;
+        pageId?: string;
+        actionId?: string;
+        baseKeyword?: string;
+        attrKeyword?: string;
+        pageNum?: number;
+        pageSize?: number;
+    }): Promise<TrackingResponse>;
+    /** Get review count for a product */
+    getReviewCount(product: string): Promise<TrackingResponse>;
+}

package/dist/tracking-client.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrackingClient = void 0;
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const url_1 = require("url");
+class TrackingClient {
+    constructor(baseUrl) {
+        this.credentials = null;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+    }
+    setCredentials(creds) {
+        this.credentials = creds;
+    }
+    isAuthenticated() {
+        return !!(this.credentials && Date.now() < this.credentials.expiresAt);
+    }
+    getCredentials() {
+        return this.credentials;
+    }
+    getOnce(apiPath, params = {}) {
+        return new Promise((resolve, reject) => {
+            if (!this.credentials) {
+                reject(new Error("Not authenticated."));
+                return;
+            }
+            const url = new url_1.URL(this.baseUrl + apiPath);
+            url.searchParams.set("u", this.credentials.uid);
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+            const mod = url.protocol === "https:" ? https_1.default : http_1.default;
+            const options = {
+                timeout: 30000,
+                headers: {
+                    "x-token": this.credentials.token,
+                    "Accept": "application/json",
+                },
+            };
+            const req = mod.get(url.toString(), options, (res) => {
+                let body = "";
+                res.on("data", (chunk) => (body += chunk));
+                res.on("end", () => {
+                    try {
+                        resolve(JSON.parse(body));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON response from ${apiPath}`));
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.on("timeout", () => {
+                req.destroy();
+                reject(new Error(`Request timeout: ${apiPath}`));
+            });
+        });
+    }
+    async get(apiPath, params = {}, retries = 2) {
+        for (let i = 0; i <= retries; i++) {
+            try {
+                return await this.getOnce(apiPath, params);
+            }
+            catch (err) {
+                if (i === retries || !err.message?.includes("timeout"))
+                    throw err;
+                console.error(`[Tracking] Retry ${i + 1}/${retries} for ${apiPath}`);
+            }
+        }
+        throw new Error(`Request failed after ${retries} retries: ${apiPath}`);
+    }
+    postOnce(apiPath, body) {
+        return new Promise((resolve, reject) => {
+            if (!this.credentials) {
+                reject(new Error("Not authenticated."));
+                return;
+            }
+            const url = new url_1.URL(this.baseUrl + apiPath);
+            url.searchParams.set("u", this.credentials.uid);
+            const mod = url.protocol === "https:" ? https_1.default : http_1.default;
+            const data = JSON.stringify(body);
+            const options = {
+                method: "POST",
+                timeout: 30000,
+                headers: {
+                    "x-token": this.credentials.token,
+                    "Content-Type": "application/json",
+                    "Content-Length": Buffer.byteLength(data),
+                    "Accept": "application/json",
+                },
+            };
+            const req = mod.request(url.toString(), options, (res) => {
+                let respBody = "";
+                res.on("data", (chunk) => (respBody += chunk));
+                res.on("end", () => {
+                    try {
+                        resolve(JSON.parse(respBody));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON response from ${apiPath}: ${respBody.substring(0, 200)}`));
+                    }
+                });
+            });
+            req.on("error", reject);
+            req.on("timeout", () => {
+                req.destroy();
+                reject(new Error(`Request timeout: ${apiPath}`));
+            });
+            req.write(data);
+            req.end();
+        });
+    }
+    async post(apiPath, body, retries = 2) {
+        for (let i = 0; i <= retries; i++) {
+            try {
+                return await this.postOnce(apiPath, body);
+            }
+            catch (err) {
+                if (i === retries || !err.message?.includes("timeout"))
+                    throw err;
+                console.error(`[Tracking] Retry ${i + 1}/${retries} for ${apiPath}`);
+            }
+        }
+        throw new Error(`Request failed after ${retries} retries: ${apiPath}`);
+    }
+    /**
+     * Download a file/image as base64.
+     * Returns { base64, contentType } or null if failed.
+     */
+    downloadFile(uuid) {
+        return new Promise((resolve) => {
+            if (!this.credentials) {
+                resolve(null);
+                return;
+            }
+            const url = new url_1.URL(`${this.baseUrl}/api/business/burial/attachment/view`);
+            url.searchParams.set("uuid", uuid);
+            url.searchParams.set("u", this.credentials.uid);
+            const mod = url.protocol === "https:" ? https_1.default : http_1.default;
+            const options = {
+                timeout: 30000,
+                headers: {
+                    "x-token": this.credentials.token,
+                    "Accept": "*/*",
+                },
+            };
+            const req = mod.get(url.toString(), options, (res) => {
+                if (res.statusCode !== 200) {
+                    resolve(null);
+                    return;
+                }
+                const chunks = [];
+                res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+                res.on("end", () => {
+                    const buffer = Buffer.concat(chunks);
+                    if (buffer.length === 0) {
+                        resolve(null);
+                        return;
+                    }
+                    const contentType = res.headers["content-type"] || "image/png";
+                    resolve({ base64: buffer.toString("base64"), contentType });
+                });
+            });
+            req.on("error", () => resolve(null));
+            req.on("timeout", () => { req.destroy(); resolve(null); });
+        });
+    }
+    // --- Business API methods ---
+    /** Get user nicknames list */
+    async getUserNickNames() {
+        return this.get("/api/bigdata/component/system/user/nickNames");
+    }
+    /** Get product names list */
+    async getProductNames() {
+        return this.post("/api/business/burial/product/names", {});
+    }
+    /** Get product types for a product */
+    async getProductTypes(productName) {
+        return this.post("/api/business/burial/product/types", { productName });
+    }
+    /** Get product versions */
+    async getProductVersions(productName, productType = "") {
+        return this.post("/api/business/burial/product/versions", { productName, productType });
+    }
+    /** Get tracking list (paginated) */
+    async getTrackingList(params) {
+        return this.post("/api/business/burial/develop/page/v2", {
+            developer: params.developer,
+            product: params.product,
+            keyWord: params.keyWord || "",
+            pageId: params.pageId || "",
+            actionId: params.actionId || "",
+            baseKeyword: params.baseKeyword || "",
+            attrKeyword: params.attrKeyword || "",
+            pageNum: params.pageNum || 1,
+            pageSize: params.pageSize || 50,
+        });
+    }
+    /** Get review count for a product */
+    async getReviewCount(product) {
+        return this.post("/api/business/burial/review/count", { product });
+    }
+}
+exports.TrackingClient = TrackingClient;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@camscanner/tracking-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for querying Intsig Data Studio tracking/burial point documentation",
+  "main": "dist/index.js",
+  "bin": {
+    "tracking-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugins",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "playwright-core": "^1.59.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}

package/plugins/tracking/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "tracking",
+  "description": "Intsig Data Studio tracking/burial point management plugin",
+  "version": "1.0.0",
+  "author": { "name": "CamScanner" }
+}

package/plugins/tracking/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "tracking": {
+    "command": "npx",
+    "args": ["-y", "@camscanner/tracking-mcp-server@latest"],
+    "env": {
+      "TRACKING_BASE_URL": "https://bigdata.intsig.net",
+      "SSO_LOGIN_URL": "https://web-sso.intsig.net/login",
+      "SSO_PLATFORM_ID": "FEOXFe858GRbG9aLymrNDLyApKcBWtrw",
+      "SSO_REDIRECT_URL": "https://ids.intsig.net/trackManage/develop"
+    }
+  }
+}

package/plugins/tracking/skills/tracking/SKILL.md

@@ -0,0 +1,70 @@
+# 埋点管理助手
+
+帮助用户通过 Tracking MCP Server 查询和管理埋点（burial point）文档。
+
+## 可用 MCP 工具
+
+来自 tracking MCP server：
+
+1. **tracking-auth** — SSO 登录（首次使用需要扫码认证）
+2. **tracking-logout** — 退出登录，清除凭证
+3. **list_products** — 列出所有可用产品名称
+4. **list_product_types** — 获取产品的平台类型（iOS/Android/Web 等）
+5. **list_product_versions** — 获取产品的版本列表
+6. **get_developer_name** — 获取当前登录开发者的显示名称
+7. **search_tracking** — 按开发者和产品搜索埋点列表（支持关键词、PageID、ActionID 过滤）
+8. **get_tracking_screenshot** — 获取埋点的截图/附件图片
+
+## 工作流程
+
+当用户请求查询埋点信息时，**按以下步骤执行**：
+
+### 第 1 步：认证检查
+
+如果尚未认证，先调用 `tracking-auth` 进行登录。
+
+### 第 2 步：获取开发者信息
+
+调用 `get_developer_name` 获取当前用户的显示名（nickName），后续查询需要用到。
+
+### 第 3 步：确定产品
+
+- 如果用户未指定产品，使用 `list_products` 列出可用产品让用户选择
+- 默认使用 "扫描全能王"
+
+### 第 4 步：查询埋点
+
+根据用户需求选择合适的工具：
+
+- **搜索埋点列表**: 使用 `search_tracking`，提供 developer（nickName）和 product
+- **按关键词搜索**: 使用 `search_tracking` 的 keyword 参数
+- **按 PageID 搜索**: 使用 `search_tracking` 的 page_id 参数
+- **查看埋点截图**: 使用 `get_tracking_screenshot`，提供 attchUuid
+
+### 第 5 步：展示结果
+
+- 以清晰的格式展示埋点信息
+- 包含 PageID、ActionID、属性参数、开发者、状态等
+- 如果有截图，可以获取并展示
+
+## 埋点数据结构说明
+
+每条埋点记录包含：
+- **id**: 唯一标识
+- **product**: 所属产品
+- **reportPlatform / devPlatform**: 上报平台 / 开发平台
+- **operation**: 埋点类型 (pageview / actionlog)
+- **pageId / pageIdZh**: 页面标识和中文名
+- **actionId / actionIdZh**: 操作标识和中文名
+- **traceId / traceIdZh**: 链路标识和中文名
+- **description**: 描述信息
+- **attchUuid**: 截图附件 UUID
+- **attributes**: 附加属性列表，每个属性包含:
+  - extKey / extKeyDesc: 参数名和描述
+  - extValue / extValueDesc: 参数值和描述
+  - extKeyType: 参数类型
+  - tag: 需求标签
+  - tapd: TAPD 链接
+  - proVersion: 版本
+  - developer / tester: 开发者 / 测试者
+  - statusCode: 状态码 (0=草稿, 5=待审核, 10=已通过, 20=已驳回, 30=已废弃)