product-spec-mcp 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.1 - Connect page user context
+
+- Added AI tool and multi-select use-case fields to the `/connect` page.
+- Stored generated token metadata as `client` and `use_case` for later product direction and billing analysis.
+- Added client-specific configuration hints/snippets to downloaded connect files for WorkBuddy, Claude Desktop, Claude Code, Codex, OpenCode, and generic Agents.
+
 ## 0.4.0 - Self-serve Online Gate connection
 
 - Added `product_spec_connect` so Agents can guide users through connecting the Online PM Gate without manual token copying.

package/README.md

@@ -208,6 +208,8 @@ Client-specific integration notes are intentionally kept out of the main user fl
   "client": "workbuddy",
   "connect_file": {
     "type": "product-spec-mcp-connect",
+    "client": "workbuddy",
+    "useCases": ["personal_app_site", "client_requirements"],
     "instructions": {
       "env": {
         "PRODUCT_SPEC_REMOTE_GATE_URL": "https://productmcp.opc-mind.top/v1/pm-intent",

package/dist/index.cjs

@@ -30154,7 +30154,7 @@ function formatConnectGuide(result) {
 function createServer() {
   const server = new McpServer({
     name: "product-spec-mcp",
-    version: "0.4.0"
+    version: "0.4.1"
   });
   registerSpecInterrogate(server);
   registerSpecCompile(server);

package/docs/connect-flow.md

@@ -31,7 +31,12 @@ https://productmcp.opc-mind.top/connect
 POST /v1/connect-token
 ```
 
-Worker 会创建一个 `psm_` 开头的专属 token，并返回连接文件。
+页面会让用户选择两个轻量字段：
+
+- 正在用哪个 AI 工具：WorkBuddy / Claude Desktop / Claude Code / Codex / OpenCode / 其他（请填写）
+- 准备用它做什么：给自己做小应用 / 网站、帮客户梳理需求、公司 / 团队内部项目、学习或测试 MCP、其他（请填写），支持多选
+
+Worker 会创建一个 `psm_` 开头的专属 token，保存这两个字段，并返回连接文件。
 
 ## Connect File
 
@@ -47,6 +52,10 @@ product-spec-mcp-connect.json
 {
   "type": "product-spec-mcp-connect",
   "version": 1,
+  "client": "workbuddy",
+  "clientKey": "workbuddy",
+  "useCase": "personal_app_site,client_requirements",
+  "useCases": ["personal_app_site", "client_requirements"],
   "remoteGate": {
     "url": "https://productmcp.opc-mind.top/v1/pm-intent",
     "token": "psm_xxx",
@@ -62,6 +71,13 @@ product-spec-mcp-connect.json
       "PRODUCT_SPEC_REMOTE_GATE_MODE": "auto",
       "PRODUCT_SPEC_REMOTE_GATE_TIMEOUT_MS": "10000",
       "PRODUCT_SPEC_TELEMETRY": "off"
+    },
+    "clientHint": {
+      "target": "WorkBuddy MCP wrapper",
+      "action": "把 instructions.env 写入 WorkBuddy 中 product-spec MCP server 的环境变量配置，然后重启 MCP。"
+    },
+    "configSnippet": {
+      "env": {}
     }
   }
 }
@@ -122,6 +138,15 @@ usage_events
 
 `api_tokens` 存 token hash，不存明文 token。`usage_events` 记录按 token 的 LLM 使用情况，后续可以接入计费、月额度、封禁和用户面板。
 
+`api_tokens` 还会保存：
+
+```sql
+client TEXT,
+use_case TEXT
+```
+
+这两个字段用于判断真实用户分布和后续生成更准确的 Agent 配置提示。
+
 ## Quotas
 
 默认每日额度仍由 Worker 变量控制：

package/docs/online-pm-gate.md

@@ -93,6 +93,8 @@ POST /v1/connect-token
 
 用户打开 `/connect` 后点击下载 `product-spec-mcp-connect.json`。文件里包含当前 Agent 应写入 MCP 配置的环境变量：
 
+页面会额外收集两个轻量字段：当前 AI 工具和主要用途。AI 工具选项是 WorkBuddy / Claude Desktop / Claude Code / Codex / OpenCode / 其他；主要用途支持多选，包括给自己做小应用 / 网站、帮客户梳理需求、公司 / 团队内部项目、学习或测试 MCP、其他。它们会写入 D1 的 token metadata，用于后续产品方向分析和生成更准确的配置片段。
+
 ```json
 {
   "PRODUCT_SPEC_REMOTE_GATE_URL": "https://productmcp.opc-mind.top/v1/pm-intent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-spec-mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP Server for product specification - requirement interrogation, architecture decision, UI translation, debug guidance, and acceptance generation",
   "type": "commonjs",
   "main": "dist/index.cjs",
@@ -14,6 +14,7 @@
     "docs/connect-flow.md",
     "docs/online-pm-gate.md",
     "workers/pm-intent-gate.mjs",
+    "workers/migrations/*.sql",
     "workers/schema.sql",
     "workers/wrangler.toml.example"
   ],

package/workers/migrations/0002_connect_metadata.sql

@@ -0,0 +1,2 @@
+ALTER TABLE api_tokens ADD COLUMN client TEXT;
+ALTER TABLE api_tokens ADD COLUMN use_case TEXT;

package/workers/pm-intent-gate.mjs

@@ -281,35 +281,45 @@ async function createConnectToken(request, env, origin) {
   const now = new Date().toISOString();
   const dailyLimit = resolveConnectTokenDailyLimit(env);
   const monthlyLimit = positiveIntegerOrNull(env.CONNECT_TOKEN_MONTHLY_LIMIT);
-  const client = sanitizeShortText(body.client || "unknown", 40);
+  const clientKey = normalizeSubmittedClient(body.client);
+  const clientOther = sanitizeOptionalText(body.clientOther || body.client_other, 60);
+  const client = clientKey === "other" && clientOther ? `other:${clientOther}` : clientKey;
+  const useCases = normalizeSubmittedUseCases(body);
+  const useCase = useCases.length > 0 ? useCases.join(",") : "unknown";
   const label = sanitizeShortText(body.label || `${client} connect token`, 80);
 
   await env.PROMPT_SAMPLES.prepare(
     `INSERT INTO api_tokens (
-      id, token_hash, token_prefix, label, daily_limit, monthly_limit, enabled, created_at, last_used_at
-    ) VALUES (?, ?, ?, ?, ?, ?, 1, ?, NULL)`
+      id, token_hash, token_prefix, label, client, use_case, daily_limit, monthly_limit, enabled, created_at, last_used_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, ?, NULL)`
   ).bind(
     id,
     tokenHash,
     token.slice(0, 12),
     label,
+    client,
+    useCase,
     dailyLimit,
     monthlyLimit,
     now
   ).run();
 
   const remoteGateUrl = resolveRemoteGateUrl(env, origin);
-  const connectFile = buildConnectFile(remoteGateUrl, token);
+  const connectFile = buildConnectFile(remoteGateUrl, token, clientKey, client, useCases);
   return json({
     ok: true,
     tokenPrefix: token.slice(0, 12),
     dailyLimit,
     monthlyLimit,
+    client,
+    clientKey,
+    useCase,
+    useCases,
     connectFile,
   });
 }
 
-function buildConnectFile(remoteGateUrl, token) {
+function buildConnectFile(remoteGateUrl, token, clientKey = "other", client = "other", useCases = []) {
   const env = {
     PRODUCT_SPEC_REMOTE_GATE_URL: remoteGateUrl,
     PRODUCT_SPEC_REMOTE_GATE_TOKEN: token,
@@ -320,6 +330,10 @@ function buildConnectFile(remoteGateUrl, token) {
   return {
     type: "product-spec-mcp-connect",
     version: 1,
+    client,
+    clientKey,
+    useCase: useCases.join(",") || "unknown",
+    useCases,
     remoteGate: {
       url: remoteGateUrl,
       token,
@@ -330,10 +344,115 @@ function buildConnectFile(remoteGateUrl, token) {
     instructions: {
       summary: "请把 remoteGate 配置写入当前 Agent 的 product-spec-mcp 环境变量。",
       env,
+      clientHint: clientConnectHint(clientKey),
+      configSnippet: clientConfigSnippet(clientKey, env),
     },
   };
 }
 
+function normalizeSubmittedClient(value) {
+  const normalized = normalizeClient(value);
+  return ["workbuddy", "claude_desktop", "claude_code", "codex", "opencode", "other"].includes(normalized)
+    ? normalized
+    : "other";
+}
+
+function normalizeSubmittedUseCases(body) {
+  const rawValues = Array.isArray(body.useCases)
+    ? body.useCases
+    : String(body.useCase || body.use_case || "")
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  const allowed = new Set(["personal_app_site", "client_requirements", "internal_team", "learning_testing", "other"]);
+  const normalized = [];
+  for (const value of rawValues) {
+    const key = String(value || "").trim();
+    if (allowed.has(key) && !normalized.includes(key)) normalized.push(key);
+  }
+  const otherText = sanitizeOptionalText(body.useCaseOther || body.use_case_other, 80);
+  if (normalized.includes("other") && otherText) {
+    normalized[normalized.indexOf("other")] = `other:${otherText}`;
+  }
+  return normalized;
+}
+
+function clientConnectHint(client) {
+  const normalized = normalizeClient(client);
+  const hints = {
+    workbuddy: {
+      target: "WorkBuddy MCP wrapper",
+      action: "把 instructions.env 写入 WorkBuddy 中 product-spec MCP server 的环境变量配置，然后重启 MCP。",
+    },
+    cursor: {
+      target: "Cursor MCP configuration",
+      action: "把 configSnippet 合并到 Cursor 的 MCP 配置；如果已有 product-spec server，只补 env。",
+    },
+    claude_desktop: {
+      target: "Claude Desktop MCP configuration",
+      action: "把 configSnippet 合并到 claude_desktop_config.json；如果已有 product-spec server，只补 env。",
+    },
+    claude_code: {
+      target: "Claude Code MCP configuration",
+      action: "把 instructions.env 写入 Claude Code 中 product-spec MCP server 的环境变量配置，然后重启 MCP。",
+    },
+    codex: {
+      target: "Codex MCP configuration",
+      action: "把 instructions.env 写入当前 Codex 可用的 product-spec MCP server 配置，然后重启 MCP。",
+    },
+    opencode: {
+      target: "opencode MCP configuration",
+      action: "把 configSnippet 合并到 ~/.config/opencode/opencode.json；如果已有 product-spec server，只补 env。",
+    },
+    other: {
+      target: "Generic MCP server configuration",
+      action: "把 instructions.env 写入 product-spec MCP server 的环境变量配置，然后重启 MCP。",
+    },
+  };
+  return hints[normalized] || hints.other;
+}
+
+function clientConfigSnippet(client, env) {
+  const normalized = normalizeClient(client);
+  if (normalized === "opencode") {
+    return {
+      mcp: {
+        "product-spec": {
+          type: "local",
+          command: ["npx", "-y", "product-spec-mcp@latest"],
+          enabled: true,
+          timeout: 30000,
+          env,
+        },
+      },
+    };
+  }
+  if (normalized === "cursor" || normalized === "claude_desktop") {
+    return {
+      mcpServers: {
+        "product-spec": {
+          command: "npx",
+          args: ["-y", "product-spec-mcp@latest"],
+          env,
+        },
+      },
+    };
+  }
+  return { env };
+}
+
+function normalizeClient(client) {
+  const value = String(client || "").toLowerCase().replace(/[\s-]+/g, "_");
+  if (value.includes("workbuddy")) return "workbuddy";
+  if (value.includes("cursor")) return "cursor";
+  if (value.includes("claude_code")) return "claude_code";
+  if (value.includes("claude") && value.includes("code")) return "claude_code";
+  if (value.includes("claude")) return "claude_desktop";
+  if (value.includes("codex")) return "codex";
+  if (value.includes("opencode")) return "opencode";
+  return ["workbuddy", "cursor", "claude_desktop", "claude_code", "codex", "opencode", "other"].includes(value) ? value : "other";
+}
+
 function connectPageHtml(origin) {
   const apiUrl = `${origin}/v1/connect-token`;
   return `<!doctype html>
@@ -352,6 +471,15 @@ function connectPageHtml(origin) {
     .steps { display: grid; gap: 12px; margin: 26px 0; padding: 0; list-style: none; }
     .steps li { display: flex; gap: 12px; align-items: flex-start; color: #243246; }
     .num { flex: 0 0 28px; height: 28px; border-radius: 999px; background: #0f766e; color: white; display: grid; place-items: center; font-weight: 700; font-size: 14px; }
+    .form { display: grid; gap: 18px; margin: 24px 0; }
+    label { display: grid; gap: 8px; font-size: 14px; font-weight: 700; color: #243246; }
+    select, input[type="text"] { width: 100%; box-sizing: border-box; border: 1px solid #d8e0eb; border-radius: 8px; background: white; color: #172033; font: inherit; padding: 12px 14px; }
+    select:focus, input[type="text"]:focus { outline: 2px solid rgba(15, 118, 110, .24); border-color: #0f766e; }
+    .hint { font-size: 13px; font-weight: 500; color: #7a8698; }
+    .hidden { display: none; }
+    .checks { display: grid; gap: 10px; }
+    .check { display: flex; gap: 10px; align-items: center; font-size: 15px; font-weight: 600; color: #243246; }
+    .check input { width: 18px; height: 18px; accent-color: #0f766e; }
     button { appearance: none; border: 0; border-radius: 8px; background: #0f766e; color: white; font-size: 16px; font-weight: 700; padding: 14px 18px; cursor: pointer; }
     button:disabled { opacity: .65; cursor: wait; }
     .status { margin-top: 16px; font-size: 14px; color: #526071; min-height: 22px; }
@@ -368,6 +496,33 @@ function connectPageHtml(origin) {
         <li><span class="num">2</span><span>把下载的 <strong>product-spec-mcp-connect.json</strong> 拖回或上传到 Agent 对话。</span></li>
         <li><span class="num">3</span><span>让 Agent 按文件里的说明完成配置并重启 MCP。</span></li>
       </ol>
+      <div class="form">
+        <label>
+          你正在用哪个 AI 工具？
+          <span class="hint">用于生成更准确的配置说明</span>
+          <select id="client">
+            <option value="workbuddy">WorkBuddy</option>
+            <option value="claude_desktop">Claude Desktop</option>
+            <option value="claude_code">Claude Code</option>
+            <option value="codex">Codex</option>
+            <option value="opencode">OpenCode</option>
+            <option value="other">其他</option>
+          </select>
+          <input id="clientOther" class="hidden" type="text" maxlength="60" placeholder="请填写 AI 工具名称">
+        </label>
+        <label>
+          你准备用它做什么？
+          <span class="hint">可多选，只用于改进 product-spec，不影响连接</span>
+          <span class="checks" id="useCases">
+            <label class="check"><input type="checkbox" value="personal_app_site" checked>给自己做小应用 / 网站</label>
+            <label class="check"><input type="checkbox" value="client_requirements">帮客户梳理需求</label>
+            <label class="check"><input type="checkbox" value="internal_team">公司 / 团队内部项目</label>
+            <label class="check"><input type="checkbox" value="learning_testing">学习或测试 MCP</label>
+            <label class="check"><input id="useCaseOtherCheck" type="checkbox" value="other">其他</label>
+          </span>
+          <input id="useCaseOther" class="hidden" type="text" maxlength="80" placeholder="请填写其他用途">
+        </label>
+      </div>
       <button id="download">生成并下载连接文件</button>
       <div class="status" id="status"></div>
       <p class="fine">连接文件里包含你的专属访问 token，请不要公开分享。默认额度由服务端配置控制。</p>
@@ -376,14 +531,31 @@ function connectPageHtml(origin) {
   <script>
     const button = document.getElementById("download");
     const status = document.getElementById("status");
+    const client = document.getElementById("client");
+    const clientOther = document.getElementById("clientOther");
+    const useCaseOtherCheck = document.getElementById("useCaseOtherCheck");
+    const useCaseOther = document.getElementById("useCaseOther");
+    client.addEventListener("change", () => {
+      clientOther.classList.toggle("hidden", client.value !== "other");
+    });
+    useCaseOtherCheck.addEventListener("change", () => {
+      useCaseOther.classList.toggle("hidden", !useCaseOtherCheck.checked);
+    });
     button.addEventListener("click", async () => {
       button.disabled = true;
       status.textContent = "正在生成连接文件...";
       try {
+        const useCases = Array.from(document.querySelectorAll("#useCases input[type='checkbox']:checked"))
+          .map((item) => item.value);
         const response = await fetch(${JSON.stringify(apiUrl)}, {
           method: "POST",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ client: "browser-connect-page" })
+          body: JSON.stringify({
+            client: client.value,
+            clientOther: clientOther.value,
+            useCases,
+            useCaseOther: useCaseOther.value
+          })
         });
         const payload = await response.json();
         if (!response.ok || !payload.connectFile) throw new Error(payload.error || "connect_failed");
@@ -426,11 +598,18 @@ function positiveIntegerOrNull(value) {
 
 function sanitizeShortText(value, maxLength) {
   return String(value || "")
-    .replace(/[^\w\s.@:-]/g, "")
+    .replace(/[^\p{L}\p{N}\s.@:_-]/gu, "")
     .trim()
     .slice(0, maxLength) || "product-spec-mcp";
 }
 
+function sanitizeOptionalText(value, maxLength) {
+  return String(value || "")
+    .replace(/[^\p{L}\p{N}\s.@:_-]/gu, "")
+    .trim()
+    .slice(0, maxLength);
+}
+
 async function callOpenAiCompatible(llm, prompt) {
   if (!llm.apiKey) throw new Error(`missing_${llm.provider}_api_key`);
   const response = await fetch(`${normalizeBaseUrl(llm.baseUrl)}/chat/completions`, {

package/workers/schema.sql

@@ -28,6 +28,8 @@ CREATE TABLE IF NOT EXISTS api_tokens (
   token_hash TEXT UNIQUE NOT NULL,
   token_prefix TEXT NOT NULL,
   label TEXT,
+  client TEXT,
+  use_case TEXT,
   daily_limit INTEGER NOT NULL,
   monthly_limit INTEGER,
   enabled INTEGER NOT NULL,