shakers-cli 0.0.0-stage → 0.14.1

package/src/mcp-choice.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// Closed questions of the MCP sign-up: a dialog when the client can elicit, otherwise one block the model prints, question last.
+
+const SAY_MESSAGE = 'Print `say` word for word as your whole reply: it already holds the texts, the question and its options as a list. Present them as a choice and pass back the exact label the talent picks, never a number; add nothing of your own and call no tool until the talent answers.';
+
+// Fixed texts that are not a question ride on the next question block: a model skips a standalone relay.
+const notices = [];
+
+function queueNotice(text) {
+  if (text && !notices.includes(text)) notices.push(text);
+}
+
+function takeNotices() {
+  return notices.splice(0);
+}
+
+// Fixed texts travel with their question, so a model that skips "show this first" still shows them.
+function sayBlock(texts, question, options) {
+  return [...texts, question, options.map((o) => `- ${o}`).join('\n')].join('\n\n');
+}
+
+function chatChoice(question, options, texts = []) {
+  return { say: sayBlock([...takeNotices(), ...texts], question, options), options, choiceMessage: SAY_MESSAGE };
+}
+
+// The option an answer names: by its label, or by a position number if the talent still types one.
+function optionFor(answer, options) {
+  if (typeof answer !== 'string') return null;
+  const text = answer.trim();
+  if (options.includes(text)) return text;
+  const n = /^\d+$/.test(text) ? Number(text) : 0;
+  return n >= 1 && n <= options.length ? options[n - 1] : null;
+}
+
+// { answer } from the dialog, { dismissed: <action> } when the talent closed it, or { chat } when there is no dialog.
+async function askChoice(ctx, { texts: own = [], question, options }) {
+  const texts = [...takeNotices(), ...own];
+  const elicit = ctx && typeof ctx.elicit === 'function' ? ctx.elicit : null;
+  const reply = elicit
+    ? await elicit({
+      message: [...texts, question].join('\n\n'),
+      requestedSchema: { type: 'object', properties: { choice: { type: 'string', title: question, enum: options } }, required: ['choice'] },
+    })
+    : null;
+  if (!reply) return { chat: chatChoice(question, options, texts) };
+  const choice = reply.action === 'accept' && reply.content ? reply.content.choice : undefined;
+  if (options.includes(choice)) return { answer: choice };
+  return { dismissed: reply.action, chat: chatChoice(question, options, texts) };
+}
+
+// A closed question after fixed texts: the chat answer the model passed back, else the dialog, else the block to print.
+async function askAfterTexts(ctx, { tool, texts, question, options, answer }) {
+  const picked = optionFor(answer, options);
+  if (picked) return { answer: picked };
+  const asked = ctx && ctx.elicitation ? await askChoice(ctx, { texts, question, options }) : { chat: chatChoice(question, options, texts) };
+  if (asked.answer) return { answer: asked.answer };
+  return {
+    reply: {
+      ok: false,
+      reason: 'answer-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...asked.chat,
+      message: `${asked.chat.choiceMessage} Then call ${tool} again with answer set to the option they pick.`,
+    },
+  };
+}
+
+// Questions this process put to the talent in the chat, keyed by exactly what they would allow:
+// an answer counts only for a question the tool asked, so a flag the AI sets by itself never does.
+const pendingConsent = new Set();
+
+// The talent's yes or no before a tool reads this computer or sends data: { granted } or { reply } to return.
+async function askConsent(ctx, { tool, key, question, yes, no, answer }) {
+  const options = [yes, no];
+  const picked = pendingConsent.has(key) ? optionFor(answer, options) : null;
+  if (picked) {
+    pendingConsent.delete(key);
+    return { granted: picked === yes };
+  }
+  const asked = ctx && ctx.elicitation ? await askChoice(ctx, { question, options }) : { chat: chatChoice(question, options) };
+  if (asked.answer) return { granted: asked.answer === yes };
+  pendingConsent.add(key);
+  return {
+    reply: {
+      ok: false,
+      reason: 'consent-required',
+      ...(asked.dismissed ? { dismissed: asked.dismissed } : {}),
+      ...asked.chat,
+      message: `Nothing was read or sent. ${asked.chat.choiceMessage} Then call ${tool} again with the same arguments and answer set to the option they pick.`,
+    },
+  };
+}
+
+module.exports = { askConsent, askChoice, askAfterTexts, chatChoice, optionFor, queueNotice, takeNotices, SAY_MESSAGE };

package/src/mcp-detector.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getHomeDir } = require('./env-paths');
+
+// KEYWORD -> { SERVICE LABEL, CATEGORY } (issue 110).
+const SERVICE_CATALOG = [
+  // --- data ---
+  { kw: 'postgresql', label: 'Postgres', category: 'data' },
+  { kw: 'postgres', label: 'Postgres', category: 'data' },
+  { kw: 'mysql', label: 'MySQL', category: 'data' },
+  { kw: 'sqlite', label: 'SQLite', category: 'data' },
+  { kw: 'mongo', label: 'MongoDB', category: 'data' },
+  { kw: 'redis', label: 'Redis', category: 'data' },
+  { kw: 'snowflake', label: 'Snowflake', category: 'data' },
+  { kw: 'bigquery', label: 'BigQuery', category: 'data' },
+  { kw: 'clickhouse', label: 'ClickHouse', category: 'data' },
+  { kw: 'dynamodb', label: 'DynamoDB', category: 'data' },
+  { kw: 'elastic', label: 'Elasticsearch', category: 'data' },
+  { kw: 'supabase', label: 'Supabase', category: 'data' },
+  { kw: 'airtable', label: 'Airtable', category: 'data' },
+  { kw: 'notion', label: 'Notion', category: 'data' },
+  { kw: 'looker', label: 'Looker', category: 'data' },
+  { kw: 'attio', label: 'Attio', category: 'data' },
+  { kw: 'sheet', label: 'Google Sheets', category: 'data' },
+  { kw: 'drive', label: 'Google Drive', category: 'data' },
+  { kw: 'database', label: null, category: 'data' },
+  // --- comms ---
+  { kw: 'slack', label: 'Slack', category: 'comms' },
+  { kw: 'discord', label: 'Discord', category: 'comms' },
+  { kw: 'gmail', label: 'Gmail', category: 'comms' },
+  { kw: 'teams', label: 'Microsoft Teams', category: 'comms' },
+  { kw: 'telegram', label: 'Telegram', category: 'comms' },
+  { kw: 'whatsapp', label: 'WhatsApp', category: 'comms' },
+  { kw: 'twilio', label: 'Twilio', category: 'comms' },
+  { kw: 'zoom', label: 'Zoom', category: 'comms' },
+  { kw: 'email', label: null, category: 'comms' },
+  { kw: 'mail', label: null, category: 'comms' },
+  { kw: 'sms', label: null, category: 'comms' },
+  // --- dev ---
+  { kw: 'github', label: 'GitHub', category: 'dev' },
+  { kw: 'gitlab', label: 'GitLab', category: 'dev' },
+  { kw: 'bitbucket', label: 'Bitbucket', category: 'dev' },
+  { kw: 'kubernetes', label: 'Kubernetes', category: 'dev' },
+  { kw: 'k8s', label: 'Kubernetes', category: 'dev' },
+  { kw: 'docker', label: 'Docker', category: 'dev' },
+  { kw: 'sentry', label: 'Sentry', category: 'dev' },
+  { kw: 'linear', label: 'Linear', category: 'dev' },
+  { kw: 'jira', label: 'Jira', category: 'dev' },
+  { kw: 'confluence', label: 'Confluence', category: 'dev' },
+  { kw: 'figma', label: 'Figma', category: 'dev' },
+  { kw: 'terraform', label: 'Terraform', category: 'dev' },
+  { kw: 'cloudflare', label: 'Cloudflare', category: 'dev' },
+  { kw: 'vercel', label: 'Vercel', category: 'dev' },
+  { kw: 'netlify', label: 'Netlify', category: 'dev' },
+  { kw: 'railway', label: 'Railway', category: 'dev' },
+  { kw: 'context7', label: 'Context7', category: 'dev' },
+  { kw: 'aws', label: 'AWS', category: 'dev' },
+  { kw: 'filesystem', label: 'Filesystem', category: 'dev' },
+  { kw: 'git', label: null, category: 'dev' },
+  // --- browser ---
+  { kw: 'playwright', label: 'Playwright', category: 'browser' },
+  { kw: 'puppeteer', label: 'Puppeteer', category: 'browser' },
+  { kw: 'browserbase', label: 'Browserbase', category: 'browser' },
+  { kw: 'browser-use', label: 'Browser Use', category: 'browser' },
+  { kw: 'stagehand', label: 'Stagehand', category: 'browser' },
+  { kw: 'chromium', label: 'Chromium', category: 'browser' },
+  { kw: 'chrome', label: 'Chrome', category: 'browser' },
+  { kw: 'browser', label: null, category: 'browser' },
+];
+
+// ORDER IS BEHAVIOUR, and it is preserved from the previous table on purpose.
+function matchService(name) {
+  const lower = String(name).toLowerCase();
+  return SERVICE_CATALOG.find((entry) => lower.includes(entry.kw)) || null;
+}
+
+function categorizeMcpServerName(name) {
+  const hit = matchService(name);
+  return hit ? hit.category : 'other';
+}
+
+// The product behind a server name, or `null` when the name does not carry one.
+function serviceForMcpServerName(name) {
+  const hit = matchService(name);
+  return hit && hit.label ? hit.label : null;
+}
+
+// THE single inventory of MCP config locations (issue 112).
+const MCP_CONFIG_LOCATIONS = [
+  // --- Claude Code (already read before 112) ---
+  { tool: 'claude-code', scope: 'project', keys: ['mcpServers'], confidence: 'high', file: (root) => path.join(root, '.mcp.json') },
+  { tool: 'claude-code', scope: 'home', keys: ['mcpServers'], confidence: 'high', file: (root, home) => path.join(home, '.claude.json') },
+  // --- Cursor: the project one was read, the GLOBAL one was the bug ---
+  { tool: 'cursor', scope: 'project', keys: ['mcpServers'], confidence: 'high', file: (root) => path.join(root, '.cursor', 'mcp.json') },
+  { tool: 'cursor', scope: 'home', keys: ['mcpServers'], confidence: 'high', file: (root, home) => path.join(home, '.cursor', 'mcp.json') },
+  // --- Windsurf (home only; no project-level MCP config known) ---
+  { tool: 'windsurf', scope: 'home', keys: ['mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, '.codeium', 'windsurf', 'mcp_config.json') },
+  // --- Gemini CLI: home was read; the project-level settings file was not ---
+  { tool: 'gemini-cli', scope: 'home', keys: ['mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, '.gemini', 'settings.json') },
+  { tool: 'gemini-cli', scope: 'project', keys: ['mcpServers'], confidence: 'medium', file: (root) => path.join(root, '.gemini', 'settings.json') },
+  // VS Code: `servers`, not `mcpServers`, and three OS-specific user paths.
+  { tool: null, scope: 'project', keys: ['servers', 'mcpServers'], confidence: 'medium', file: (root) => path.join(root, '.vscode', 'mcp.json') },
+  { tool: null, scope: 'home', keys: ['servers', 'mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json') },
+  { tool: null, scope: 'home', keys: ['servers', 'mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, '.config', 'Code', 'User', 'mcp.json') },
+  { tool: null, scope: 'home', keys: ['servers', 'mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, 'AppData', 'Roaming', 'Code', 'User', 'mcp.json') },
+  // --- Claude Desktop: same `mcpServers` shape, three OS-specific paths ---
+  { tool: null, scope: 'home', keys: ['mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json') },
+  { tool: null, scope: 'home', keys: ['mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, '.config', 'Claude', 'claude_desktop_config.json') },
+  { tool: null, scope: 'home', keys: ['mcpServers'], confidence: 'medium', file: (root, home) => path.join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json') },
+];
+
+// Reads ONLY the top-level keys of the server map from one config file, trying
+// each declared key in order. Never reads or returns any value under those keys.
+function readMcpServerNames(file, keys = ['mcpServers']) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!obj || typeof obj !== 'object') return [];
+  for (const key of keys) {
+    const servers = obj[key];
+    if (servers && typeof servers === 'object' && !Array.isArray(servers)) return Object.keys(servers);
+  }
+  return [];
+}
+
+// Deterministic (no-LLM) MCP-by-name detection over every location in `MCP_CONFIG_LOCATIONS` (project ∪ home).
+function detectMcpServers(root) {
+  const home = getHomeDir();
+  // name -> { scopes:Set, tools:Set }
+  const found = new Map();
+  const byTool = {};
+
+  for (const loc of MCP_CONFIG_LOCATIONS) {
+    let file;
+    try {
+      file = loc.file(root, home);
+    } catch {
+      continue; // an unresolvable home never breaks the other locations
+    }
+    const names = readMcpServerNames(file, loc.keys);
+    if (loc.tool && names.length) {
+      // Per-tool count is the union across THAT tool's own locations, so a
+      // server configured both in the project and globally counts once for it.
+      const set = byTool[`__set_${loc.tool}`] || (byTool[`__set_${loc.tool}`] = new Set());
+      for (const n of names) set.add(n);
+    }
+    for (const name of names) {
+      const entry = found.get(name) || { scopes: new Set(), tools: new Set() };
+      entry.scopes.add(loc.scope);
+      if (loc.tool) entry.tools.add(loc.tool);
+      found.set(name, entry);
+    }
+  }
+
+  // Collapse the per-tool sets into plain counts (and drop the working keys).
+  for (const key of Object.keys(byTool)) {
+    if (key.startsWith('__set_')) {
+      byTool[key.slice('__set_'.length)] = byTool[key].size;
+      delete byTool[key];
+    }
+  }
+
+  const servers = [...found.keys()]
+    .sort()
+    .map((name) => {
+      const entry = found.get(name);
+      return {
+        name,
+        category: categorizeMcpServerName(name),
+        // 'project' wins when a server is declared in both: the most specific
+        // scope is the honest label for "this repo uses it".
+        scope: entry.scopes.has('project') ? 'project' : 'home',
+        // Issue 110: the PRODUCT, derived from the name only. `null` when the
+        // name carries none — a state, not a hole.
+        service: serviceForMcpServerName(name),
+      };
+    });
+
+  return buildMcpAggregate(servers, byTool);
+}
+
+// Builds the report's `mcp` block from an already-resolved server list + the per-tool counts.
+function buildMcpAggregate(servers, byTool = {}) {
+  const sorted = [...servers].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  const countsByCategory = { data: 0, comms: 0, dev: 0, browser: 0, other: 0 };
+  for (const s of sorted) countsByCategory[s.category] += 1;
+
+  const byService = new Map();
+  let unidentified = 0;
+  for (const s of sorted) {
+    if (!s.service) {
+      unidentified += 1;
+      continue;
+    }
+    byService.set(s.service, (byService.get(s.service) || 0) + 1);
+  }
+  const services = [...byService.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([label, count]) => ({ label, count }));
+
+  return { servers: sorted, services, unidentified, countsByCategory, total: sorted.length, byTool };
+}
+
+module.exports = {
+  detectMcpServers,
+  buildMcpAggregate,
+  categorizeMcpServerName,
+  serviceForMcpServerName,
+  MCP_CONFIG_LOCATIONS,
+  SERVICE_CATALOG,
+};

package/src/mcp-device-login-tools.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// MCP: two provider-agnostic tools (start returns URL+user_code to relay VERBATIM; poll finishes). device_code stays in the local store, never in a result.
+
+const START_SCHEMA = {
+  type: 'object',
+  properties: {
+    provider: { type: 'string', enum: ['google', 'linkedin', 'email'], description: "Optional provider. Defaults to 'google'. Same device flow either way; it selects which option the Shakers sign-in page opens — 'email' opens the email sign-in (the talent reuses their open web session or signs in there, never a password in the chat)." },
+    mode: { type: 'string', enum: ['login', 'register'], description: "Optional. 'login' signs an existing talent in; 'register' creates the account if new (the profile steps come from the register/onboarding tools afterwards). Defaults to 'login'." },
+    freelanceType: { type: 'string', description: 'Optional, register only: FREELANCE | EMPLOYEE | AGENCY | POTENTIAL_FREELANCE. Used to complete a new account.' },
+    preferredLanguage: { type: 'string', description: 'Optional, register only: es | en | it | pt | fr.' },
+  },
+};
+
+const POLL_SCHEMA = { type: 'object', properties: {} };
+
+function makeDeviceLoginTools(deps = {}) {
+  const {
+    getDeviceAuthorizeEndpoint = require('./config').getDeviceAuthorizeEndpoint,
+    getDeviceTokenEndpoint = require('./config').getDeviceTokenEndpoint,
+    getAuthTokenEndpoint = require('./config').getAuthTokenEndpoint,
+    getCompleteRegistrationEndpoint = require('./config').getCompleteRegistrationEndpoint,
+    startDeviceLogin = require('./device-login').startDeviceLogin,
+    pollDeviceToken = require('./device-login').pollDeviceToken,
+    finalizeDeviceSession = require('./device-login').finalizeDeviceSession,
+    appendProviderParam = require('./device-login').appendProviderParam,
+    savePendingDevice = require('./device-auth-store').savePendingDevice,
+    loadPendingDevice = require('./device-auth-store').loadPendingDevice,
+    clearPendingDevice = require('./device-auth-store').clearPendingDevice,
+    saveAuthSession = require('./auth-session-store').saveAuthSession,
+    buildRegistrationContext = require('./signup-client').buildRegistrationContext,
+  } = deps;
+
+  async function start(args = {}) {
+    const mode = args.mode === 'register' ? 'register' : 'login';
+    const provider = args.provider === 'linkedin' ? 'linkedin' : args.provider === 'email' ? 'email' : 'google';
+    const authorizeEndpoint = getDeviceAuthorizeEndpoint();
+    const tokenEndpoint = getDeviceTokenEndpoint();
+    const authTokenEndpoint = getAuthTokenEndpoint();
+    if (!authorizeEndpoint || !tokenEndpoint || !authTokenEndpoint) {
+      return { ok: false, reason: 'no-endpoint', message: 'No sign-in endpoint configured — set SHAKERS_CLI_HUB_BASE.' };
+    }
+
+    const authz = await startDeviceLogin({ authorizeEndpoint });
+    if (!authz.ok) return { ok: false, reason: authz.reason || 'authorize-failed' };
+
+    const verificationUrl = appendProviderParam(authz.verificationUriComplete, provider);
+    const expiresAt = new Date(Date.now() + authz.expiresIn * 1000).toISOString();
+    try {
+      savePendingDevice({
+        deviceCode: authz.deviceCode,
+        verificationUrl,
+        userCode: authz.userCode,
+        tokenEndpoint,
+        authTokenEndpoint,
+        interval: authz.interval,
+        expiresAt,
+        mode,
+        provider,
+        registerContext: mode === 'register'
+          ? { freelanceType: args.freelanceType || null, preferredLanguage: args.preferredLanguage || null }
+          : null,
+      });
+    } catch {
+      return { ok: false, reason: 'pending-persist-failed' };
+    }
+
+    return {
+      ok: true,
+      status: 'pending',
+      provider,
+      verificationUrl,
+      verificationUri: authz.verificationUri,
+      userCode: authz.userCode,
+      expiresInSeconds: authz.expiresIn,
+      pollIntervalSeconds: authz.interval,
+      message: `Show the talent this link and code so they can authorize in their own browser — relay both verbatim, do not invent or complete the code:\n\n${verificationUrl}\n\nCode: ${authz.userCode}\n\nThen call social_signin_poll; if it returns status "pending", wait pollIntervalSeconds and call it again.`,
+    };
+  }
+
+  async function poll() {
+    const pending = loadPendingDevice();
+    if (!pending || !pending.deviceCode) {
+      return { ok: false, status: 'no-pending', message: 'No social sign-in is in progress — call social_signin_start first.' };
+    }
+
+    const res = await pollDeviceToken({ deviceCode: pending.deviceCode, tokenEndpoint: pending.tokenEndpoint });
+
+    const linkBlock = pending.verificationUrl
+      ? `\n\n${pending.verificationUrl}\n\nCode: ${pending.userCode || ''}`
+      : '';
+
+    if (res.status === 'pending') {
+      return {
+        ok: true,
+        status: 'pending',
+        pollIntervalSeconds: pending.interval,
+        verificationUrl: pending.verificationUrl,
+        userCode: pending.userCode,
+        message: `Not authorized yet. Keep showing the talent this link and code so they can finish in their browser:${linkBlock}\n\nThen wait pollIntervalSeconds and call social_signin_poll again.`,
+      };
+    }
+    if (res.status === 'slow_down') {
+      const interval = pending.interval + 5;
+      try { savePendingDevice({ ...pending, interval }); } catch { /* keep the old interval */ }
+      return {
+        ok: true,
+        status: 'pending',
+        pollIntervalSeconds: interval,
+        verificationUrl: pending.verificationUrl,
+        userCode: pending.userCode,
+        message: `Polling too fast — wait pollIntervalSeconds and call social_signin_poll again. Keep the talent's link and code visible:${linkBlock}`,
+      };
+    }
+    if (res.status === 'denied') {
+      clearPendingDevice();
+      return { ok: false, status: 'denied', message: 'The talent cancelled or did not grant access. No session was started.' };
+    }
+    if (res.status === 'expired') {
+      clearPendingDevice();
+      return { ok: false, status: 'expired', message: 'The sign-in request expired. Call social_signin_start to try again.' };
+    }
+    if (res.status !== 'authorized') {
+      return { ok: false, status: 'error', reason: res.reason || 'poll-failed' };
+    }
+
+    // finalize enforces the order: NEW user -> complete-registration before the JWT exchange. freelanceType is a transient default.
+    const rc = pending.registerContext || {};
+    const registrationContext = buildRegistrationContext({
+      preferredLanguage: rc.preferredLanguage || undefined,
+      newsletterConsent: false,
+      freelanceType: rc.freelanceType || 'POTENTIAL_FREELANCE',
+    });
+    const fin = await finalizeDeviceSession({
+      sessionToken: res.accessToken,
+      isNewUser: res.isNewUser,
+      authTokenEndpoint: pending.authTokenEndpoint,
+      completeRegistrationEndpoint: getCompleteRegistrationEndpoint(),
+      registrationContext,
+    });
+    if (!fin.ok) {
+      // The authorization was consumed; a re-poll can't recover — never treat this as logged in.
+      clearPendingDevice();
+      return { ok: false, status: 'error', reason: fin.reason };
+    }
+    try {
+      saveAuthSession({ accessToken: fin.token, hubAccessToken: fin.token, email: res.email || pending.email || null });
+    } catch {
+      clearPendingDevice();
+      return { ok: false, status: 'error', reason: 'session-persist-failed' };
+    }
+
+    clearPendingDevice();
+    return { ok: true, status: 'authorized', method: pending.provider || 'google', email: res.email || null, isNewUser: !!res.isNewUser };
+  }
+
+  return [
+    {
+      name: 'social_signin_start',
+      title: 'Sign in to Shakers',
+      description: 'Opens a Shakers page in your browser where you sign in with Google, LinkedIn or your email. Your password never goes through the chat.',
+      guidance: "Begin sign-in (or registration) via the device flow — provider 'google' (default), 'linkedin' or 'email'. Email goes through the SAME web flow: the talent reuses their open Shakers session or signs in with their email on the page, never a password in the chat. Returns a verificationUrl and a userCode: show BOTH to the talent verbatim — they open the URL and enter the code in their own browser (they never type anything in the chat, and you never invent or fill the code). Pass mode 'register' to create the account if it is new. After showing them, call social_signin_poll. Returns { ok, status, provider, verificationUrl, userCode, pollIntervalSeconds, ... }.",
+      inputSchema: START_SCHEMA,
+      handler: start,
+    },
+    {
+      name: 'social_signin_poll',
+      title: 'Finish signing in',
+      description: 'Checks whether you finished signing in on that page and, if so, keeps you signed in on this computer.',
+      guidance: "Check whether the talent has finished the social sign-in started by social_signin_start, and persist the session when they have. Call it after showing the code; if it returns status 'pending', wait pollIntervalSeconds and call it again — the 'pending' response repeats the verificationUrl and userCode so you can keep the clickable link in front of the talent. Returns status 'authorized' (session saved, with isNewUser + method), 'pending', 'denied', or 'expired'.",
+      inputSchema: POLL_SCHEMA,
+      handler: poll,
+    },
+  ];
+}
+
+module.exports = { makeDeviceLoginTools, START_SCHEMA, POLL_SCHEMA };

package/src/mcp-find-projects-tools.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// MCP: list the Positions/Projects available to the talent (Find Positions),
+// paginated + filtered server-side. Same params as the CLI so an agent can page.
+
+const { TABS, ATTENDANCE, DEFAULT_LIMIT } = require('./find-projects-client');
+const { splitRecommended } = require('./find-projects-flow');
+
+const FIND_PROJECTS_SCHEMA = {
+  type: 'object',
+  properties: {
+    tab: { type: 'string', enum: TABS, description: 'all (default order, match desc) or saved (bookmarked).' },
+    page: { type: 'integer', minimum: 1, description: '1-based page. offset = (page-1)*limit.' },
+    limit: { type: 'integer', minimum: 1, maximum: 50, description: `Items per page (default ${DEFAULT_LIMIT}, max 50).` },
+    attendance: { type: 'string', enum: Object.keys(ATTENDANCE), description: 'Work mode filter (server-side).' },
+    country: { type: 'string', description: 'ISO 3166-1 alpha-2 country filter (server-side).' },
+    recommended: { type: 'boolean', description: 'Client-side: keep only items with a match on this page. If none, falls back to the available items (never empty). `recommended` in the result is "recommended" | "fallback" | null.' },
+  },
+};
+
+function makeFindProjectsTools(deps = {}) {
+  const {
+    fetchFindProjects = (opts) => require('./find-projects-client').fetchFindProjects({}, opts),
+    loadAuthSession = require('./auth-session-store').loadAuthSession,
+    sessionStatus = require('./auth-session-store').sessionStatus,
+  } = deps;
+
+  const requireLoginSession = () => {
+    const session = loadAuthSession();
+    if (sessionStatus(session) !== 'active') {
+      throw new Error('no active Shakers session — sign in with social_signin_start (or run `shakers login`) first (find_projects is session-gated).');
+    }
+    return session;
+  };
+
+  async function findProjects(args = {}) {
+    const session = requireLoginSession();
+    const tab = TABS.includes(args.tab) ? args.tab : 'all';
+    const limit = Number.isInteger(args.limit) && args.limit > 0 ? Math.min(args.limit, 50) : DEFAULT_LIMIT;
+    const page = Number.isInteger(args.page) && args.page > 0 ? args.page : 1;
+    const offset = (page - 1) * limit;
+    const attRaw = typeof args.attendance === 'string' ? args.attendance.trim().toLowerCase() : null;
+    const attendance = attRaw && ATTENDANCE[attRaw] ? ATTENDANCE[attRaw] : null;
+    const countryRaw = typeof args.country === 'string' ? args.country.trim().toUpperCase() : null;
+    const country = countryRaw && /^[A-Z]{2}$/.test(countryRaw) ? countryRaw : null;
+
+    const res = await fetchFindProjects({ hubAccessToken: session.hubAccessToken, tab, limit, offset, attendance, country });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    // Same client-side recommended filter (+ fallback to available) as the CLI.
+    const { shown, mode } = splitRecommended(res.items || [], !!args.recommended);
+    return { ok: true, tab, page, limit, filters: { attendance, country, recommended: !!args.recommended }, recommended: mode, meta: res.meta || null, items: shown };
+  }
+
+  return [
+    {
+      name: 'find_projects',
+      title: 'Find projects',
+      description: 'Shows the open Shakers projects that match you best.',
+      guidance: "List the Positions/Projects available to the talent right now (Shakers Find Positions), paginated and ordered by match desc. Each item carries its parent Project id/name, title, company, budget, work mode and match. Supports server-side pagination (page/limit) and filters (tab all|saved, attendance, country ISO2). `meta` carries {page,pageSize,total,totalPages}. Requires an active session. The positionId/projectId in each item are INTERNAL handles for calling other tools (e.g. show_project, save_project) — NEVER show or mention them to the talent; refer to a project by its title/company only.",
+      inputSchema: FIND_PROJECTS_SCHEMA,
+      handler: findProjects,
+    },
+  ];
+}
+
+module.exports = {
+  makeFindProjectsTools,
+  FIND_PROJECTS_SCHEMA,
+};