shakers-cli-beta 0.8.0-beta.0

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

@@ -0,0 +1,173 @@
+'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'], description: "Optional social provider. Defaults to 'google'. Same device flow either way; it selects which social button the sign-in page opens." },
+    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' : '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',
+      description: "Begin social sign-in (or registration) via the device flow — provider 'google' (default) or 'linkedin'. 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',
+      description: "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,67 @@
+'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 — call the login tool (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',
+      description: "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,
+};

package/src/mcp-install.js

@@ -0,0 +1,245 @@
+'use strict';
+
+// Run by install.sh as its last step: points every MCP client found on this machine at this CLI's
+// `mcp` server. Absolute paths, because Claude Desktop launched from the Dock has no
+// shell PATH and a bare `"command": "shakers"` never starts.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SERVER_NAME = 'shakers';
+// The name the first published setup guide used.
+const LEGACY_SERVER_NAME = 'shakers-ai-usage';
+const FORWARDED_ENV = [
+  'SHAKERS_PROFILE',
+  'SHAKERS_CLI_CERTS_BASE',
+  'SHAKERS_CLI_HUB_BASE',
+  'SHAKERS_CLI_PROFILE_URL',
+  'SHAKERS_CLI_INGEST_ENDPOINT',
+];
+
+// The `node` the shell finds on PATH, unresolved: Homebrew's /opt/homebrew/bin/node survives
+// `brew upgrade node`, the versioned Cellar path process.execPath points at does not.
+function stableNodePath(env, execPath) {
+  const exe = process.platform === 'win32' ? 'node.exe' : 'node';
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, exe);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.realpathSync(candidate) === fs.realpathSync(execPath)) return candidate;
+    } catch {
+      // not this one
+    }
+  }
+  return execPath;
+}
+
+function serverEntry({ nodePath, cliPath, env }) {
+  const entryEnv = {};
+  if (env.PATH) entryEnv.PATH = env.PATH;
+  for (const key of FORWARDED_ENV) if (env[key]) entryEnv[key] = env[key];
+  return { command: nodePath, args: [cliPath, 'mcp'], env: entryEnv };
+}
+
+function claudeDesktopConfigPath({ platform, homedir, env }) {
+  if (platform === 'darwin') return path.join(homedir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  if (platform === 'win32') return path.join(env.APPDATA || path.join(homedir, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+  return path.join(homedir, '.config', 'Claude', 'claude_desktop_config.json');
+}
+
+function writeJsonAtomic(file, value, mode) {
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+  const fd = fs.openSync(tmp, 'wx', mode);
+  try {
+    fs.writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    fs.fsyncSync(fd);
+  } catch (e) {
+    fs.closeSync(fd);
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+  fs.closeSync(fd);
+  fs.renameSync(tmp, file);
+}
+
+const sameEntry = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Merges our entry into a client's JSON config, leaving every other key as it was.
+function installIntoJsonConfig(file, entry, key = 'mcpServers') {
+  if (!fs.existsSync(path.dirname(file))) return { status: 'not-found' };
+  let config = {};
+  let mode = 0o600;
+  if (fs.existsSync(file)) {
+    const raw = fs.readFileSync(file, 'utf8');
+    try {
+      config = raw.trim() ? JSON.parse(raw) : {};
+    } catch {
+      return { status: 'invalid-json' };
+    }
+    if (!config || typeof config !== 'object' || Array.isArray(config)) return { status: 'invalid-json' };
+    mode = fs.statSync(file).mode & 0o777;
+  }
+  const current = config[key];
+  if (current !== undefined && (!current || typeof current !== 'object' || Array.isArray(current))) {
+    return { status: 'invalid-json' };
+  }
+  const servers = current || {};
+  const legacy = Object.prototype.hasOwnProperty.call(servers, LEGACY_SERVER_NAME);
+  if (!legacy && sameEntry(servers[SERVER_NAME], entry)) return { status: 'unchanged' };
+
+  const next = { ...config, [key]: { ...servers, [SERVER_NAME]: entry } };
+  delete next[key][LEGACY_SERVER_NAME];
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+  writeJsonAtomic(file, next, mode);
+  return { status: 'configured', removedLegacy: legacy };
+}
+
+function installIntoClaudeCode(entry, { spawn }) {
+  spawn('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME], { encoding: 'utf8' });
+  const envFlags = Object.entries(entry.env).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
+  const added = spawn(
+    'claude',
+    // Name first: `-e` takes every value up to `--`, so a name after it is read as one more variable.
+    ['mcp', 'add', SERVER_NAME, '--scope', 'user', ...envFlags, '--', entry.command, ...entry.args],
+    { encoding: 'utf8' },
+  );
+  if (added.error || added.status !== 0) return { status: 'failed' };
+  return { status: 'configured' };
+}
+
+function installIntoCodex(entry, { spawn }) {
+  spawn('codex', ['mcp', 'remove', SERVER_NAME], { encoding: 'utf8' });
+  const envFlags = Object.entries(entry.env).flatMap(([k, v]) => ['--env', `${k}=${v}`]);
+  const added = spawn('codex', ['mcp', 'add', SERVER_NAME, ...envFlags, '--', entry.command, ...entry.args], { encoding: 'utf8' });
+  if (added.error || added.status !== 0) return { status: 'failed' };
+  return { status: 'configured' };
+}
+
+function vscodeUserDir({ platform, homedir, env }) {
+  if (platform === 'darwin') return path.join(homedir, 'Library', 'Application Support', 'Code', 'User');
+  if (platform === 'win32') return path.join(env.APPDATA || path.join(homedir, 'AppData', 'Roaming'), 'Code', 'User');
+  return path.join(homedir, '.config', 'Code', 'User');
+}
+
+function clientTable({ env, platform, homedir, spawn }) {
+  const hasCli = (bin) => {
+    const probe = spawn(bin, ['--version'], { encoding: 'utf8' });
+    return !probe.error && probe.status === 0;
+  };
+  const jsonClient = (client, file, key, shape = (entry) => entry) => ({
+    client,
+    found: () => fs.existsSync(path.dirname(file)),
+    install: (entry) => installIntoJsonConfig(file, shape(entry), key),
+  });
+  return [
+    jsonClient('claudeDesktop', claudeDesktopConfigPath({ platform, homedir, env })),
+    { client: 'claudeCode', found: () => hasCli('claude'), install: (entry) => installIntoClaudeCode(entry, { spawn }) },
+    jsonClient('cursor', path.join(homedir, '.cursor', 'mcp.json')),
+    jsonClient('geminiCli', path.join(homedir, '.gemini', 'settings.json')),
+    { client: 'codex', found: () => hasCli('codex'), install: (entry) => installIntoCodex(entry, { spawn }) },
+    // VS Code keys servers under "servers" and wants the transport spelled out.
+    jsonClient('vscode', path.join(vscodeUserDir({ platform, homedir, env }), 'mcp.json'), 'servers', (entry) => ({ type: 'stdio', ...entry })),
+    jsonClient('windsurf', path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json')),
+  ];
+}
+
+const guard = (task) => {
+  try {
+    return task();
+  } catch {
+    return { status: 'failed' };
+  }
+};
+
+/** The AI apps on this machine that can take the MCP. */
+function detectMcpClients({ env = process.env, platform = process.platform, homedir = os.homedir(), spawn = spawnSync } = {}) {
+  return clientTable({ env, platform, homedir, spawn })
+    .filter((c) => guard(() => c.found()) === true)
+    .map((c) => c.client);
+}
+
+function installMcpClients({
+  env = process.env,
+  platform = process.platform,
+  homedir = os.homedir(),
+  nodePath = stableNodePath(env, process.execPath),
+  cliPath = fs.realpathSync(path.join(__dirname, '..', 'bin', 'shakers.js')),
+  spawn = spawnSync,
+} = {}) {
+  const entry = serverEntry({ nodePath, cliPath, env });
+  return {
+    entry,
+    results: clientTable({ env, platform, homedir, spawn }).map((c) => ({
+      client: c.client,
+      ...(guard(() => c.found()) === true ? guard(() => c.install(entry)) : { status: 'not-found' }),
+    })),
+  };
+}
+
+// The Talent's answer, read from the terminal: under `curl | bash` stdin is the script.
+function askTerminal(question) {
+  let fd;
+  try {
+    fd = fs.openSync('/dev/tty', 'r+');
+  } catch {
+    return Promise.resolve(null);
+  }
+  const tty = require('tty');
+  const readline = require('readline');
+  const input = new tty.ReadStream(fd);
+  const output = new tty.WriteStream(fd);
+  const rl = readline.createInterface({ input, output });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      input.destroy();
+      output.destroy();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Asks before touching the Talent's AI apps. SHAKERS_MCP_INSTALL=1 answers yes
+ * without asking; with no terminal to ask on, nothing is touched.
+ */
+async function runMcpInstall({ out = (s) => process.stdout.write(s), lang = null, ask = askTerminal, ...deps } = {}) {
+  const { getCatalog, detectFlowLang } = require('./i18n');
+  const c = getCatalog(lang || detectFlowLang()).mcpInstall;
+  const env = deps.env || process.env;
+  const found = detectMcpClients(deps);
+  out(`\n  ${c.title}\n\n`);
+  if (found.length === 0) {
+    out(`  ${c.noneFound}\n\n`);
+    return { ok: true, results: [] };
+  }
+  out(`  ${c.found(found.map((client) => c.clients[client]).join(', '))}\n`);
+  let yes = env.SHAKERS_MCP_INSTALL === '1';
+  if (!yes) {
+    const answer = await ask(`  ${c.confirm} `);
+    if (answer === null) {
+      out(`\n  ${c.noTerminal}\n\n`);
+      return { ok: true, results: [], declined: true };
+    }
+    yes = !/^\s*(n|no)\s*$/i.test(answer);
+  }
+  if (!yes) {
+    out(`\n  ${c.declined}\n\n`);
+    return { ok: true, results: [], declined: true };
+  }
+
+  const { results } = installMcpClients(deps);
+  out('\n');
+  for (const r of results.filter((x) => x.status !== 'not-found')) {
+    out(`  ${c.clients[r.client]}: ${c.status[r.status]}\n`);
+    if (r.removedLegacy) out(`    ${c.removedLegacy}\n`);
+  }
+  out(`\n  ${c.restart}\n\n`);
+  if (results.some((r) => r.status === 'failed' || r.status === 'invalid-json')) process.exitCode = 1;
+  return { ok: true, results };
+}
+
+module.exports = { detectMcpClients, installMcpClients, stableNodePath, runMcpInstall, serverEntry, claudeDesktopConfigPath, SERVER_NAME, LEGACY_SERVER_NAME };

package/src/mcp-invitations-tools.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// MCP: the talent's unread position invitations.
+
+const LIST_INVITATIONS_SCHEMA = { type: 'object', properties: {} };
+
+function makeInvitationsTools(deps = {}) {
+  const {
+    fetchInvitations = (opts) => require('./invitations-client').fetchInvitations({}, 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 — call the login tool (or run `shakers login`) first (list_invitations is session-gated).');
+    }
+    return session;
+  };
+
+  async function listInvitations() {
+    const session = requireLoginSession();
+    const res = await fetchInvitations({ hubAccessToken: session.hubAccessToken });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, invitations: res.items || [] };
+  }
+
+  return [
+    {
+      name: 'list_invitations',
+      description: "List the talent's unread position invitations (projects that invited them). Requires an active session. Any projectId/chatId in the result are INTERNAL handles for calling tools — never show or mention them to the talent; refer to a project by its name.",
+      inputSchema: LIST_INVITATIONS_SCHEMA,
+      handler: listInvitations,
+    },
+  ];
+}
+
+module.exports = {
+  makeInvitationsTools,
+  LIST_INVITATIONS_SCHEMA,
+};

package/src/mcp-lang-tools.js

@@ -0,0 +1,39 @@
+'use strict';
+
+// MCP: view the talent's languages. Read-only (editing is CLI-only).
+
+const GET_LANGUAGES_SCHEMA = { type: 'object', properties: {} };
+
+function makeLangTools(deps = {}) {
+  const {
+    fetchLanguages = (opts) => require('./lang-client').fetchLanguages({}, 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 — call the login tool (or run `shakers login`) first (get_languages is session-gated).');
+    }
+    return session;
+  };
+
+  async function getLanguages() {
+    const session = requireLoginSession();
+    const res = await fetchLanguages({ hubAccessToken: session.hubAccessToken });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, languages: res.languages };
+  }
+
+  return [
+    {
+      name: 'get_languages',
+      description: "View the talent's languages and proficiency levels (NATIVE/ADVANCED/INTERMEDIATE/INTERMEDIATE_WRITTEN). Read-only. Requires an active session. Any language ids in the result are internal handles for tools only — never show or mention them to the talent; refer to a language by its name.",
+      inputSchema: GET_LANGUAGES_SCHEMA,
+      handler: getLanguages,
+    },
+  ];
+}
+
+module.exports = { makeLangTools, GET_LANGUAGES_SCHEMA };