shakers-cli 0.0.0-stage → 0.14.1

package/src/mcp-server.js

@@ -0,0 +1,290 @@
+'use strict';
+
+const readline = require('readline');
+
+const JSONRPC = '2.0';
+const DEFAULT_PROTOCOL_VERSION = '2025-06-18';
+// A talent answering a dialog takes human time; past this the tool falls back to asking in the chat.
+const ELICITATION_TIMEOUT_MS = 5 * 60 * 1000;
+const ELICITATION_ACTIONS = new Set(['accept', 'decline', 'cancel']);
+
+const ERROR = {
+  PARSE: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL: -32603,
+};
+
+function isResponse(msg) {
+  return !!msg && msg.jsonrpc === JSONRPC && msg.method === undefined && msg.id !== undefined && msg.id !== null && ('result' in msg || 'error' in msg);
+}
+
+function isNotification(msg) {
+  return !msg || msg.id === undefined || msg.id === null;
+}
+
+function resultResponse(id, result) {
+  return { jsonrpc: JSONRPC, id, result };
+}
+
+function errorResponse(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  return { jsonrpc: JSONRPC, id: id === undefined ? null : id, error };
+}
+
+function createMcpServer({ tools = [], prompts = [], serverInfo = {}, protocolVersion, beforeCall = null, onInitialize = null, instructions = null, elicitationTimeoutMs = ELICITATION_TIMEOUT_MS } = {}) {
+  const registry = new Map();
+  for (const t of tools) {
+    if (!t || !t.name || typeof t.handler !== 'function') {
+      throw new Error('each tool needs a name and a handler function');
+    }
+    registry.set(t.name, t);
+  }
+
+  const promptRegistry = new Map();
+  for (const p of prompts) {
+    if (!p || !p.name || typeof p.buildMessages !== 'function') {
+      throw new Error('each prompt needs a name and a buildMessages function');
+    }
+    promptRegistry.set(p.name, p);
+  }
+
+  const advertisedVersion = protocolVersion || DEFAULT_PROTOCOL_VERSION;
+
+  let clientCapabilities = {};
+  let send = null;
+  let lastRequestId = 0;
+  const pending = new Map();
+
+  function request(method, params, timeoutMs) {
+    if (!send) return Promise.reject(new Error('no transport to the client'));
+    lastRequestId += 1;
+    const id = `shakers-${lastRequestId}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); reject(new Error(`${method} timed out`)); }, timeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      send({ jsonrpc: JSONRPC, id, method, params });
+    });
+  }
+
+  function settle(msg) {
+    const waiter = pending.get(msg.id);
+    if (!waiter) return;
+    pending.delete(msg.id);
+    clearTimeout(waiter.timer);
+    if (msg.error) waiter.reject(new Error((msg.error && msg.error.message) || 'client error'));
+    else waiter.resolve(msg.result);
+  }
+
+  function rejectPending(reason) {
+    for (const [id, waiter] of pending) {
+      pending.delete(id);
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(reason));
+    }
+  }
+
+  // The spec (2025-06-18) advertises elicitation support as a presence flag: `capabilities.elicitation: {}`.
+  // So any advertised elicitation can ask a closed question — except an explicit url-only object
+  // (`{ url }` without `{ form }`), which only opens links and falls back to the chat.
+  function canElicitForm() {
+    const e = clientCapabilities.elicitation;
+    if (!e) return false;
+    if (typeof e === 'object' && e.url !== undefined && e.form === undefined) return false;
+    return true;
+  }
+
+  // MCP elicitation/create: the client's { action, content }, or null when it has no dialog or the exchange failed.
+  async function elicit({ message, requestedSchema }) {
+    if (!send || !canElicitForm()) return null;
+    try {
+      const result = await request('elicitation/create', { message, requestedSchema }, elicitationTimeoutMs);
+      return result && ELICITATION_ACTIONS.has(result.action) ? result : null;
+    } catch {
+      return null;
+    }
+  }
+
+  // `description` and `title` are what the talent reads in the client; `guidance` is how the model must use the tool, so it rides in the schema.
+  function shapeTool(t) {
+    const schema = t.inputSchema || { type: 'object' };
+    return {
+      name: t.name,
+      ...(t.title ? { title: t.title } : {}),
+      description: t.description || '',
+      inputSchema: t.guidance ? { ...schema, description: [t.guidance, schema.description].filter(Boolean).join(' ') } : schema,
+    };
+  }
+
+  function listTools() {
+    return { tools: [...registry.values()].map(shapeTool) };
+  }
+
+  function shapePrompt(p) {
+    const out = { name: p.name, description: p.description || '' };
+    if (Array.isArray(p.arguments)) out.arguments = p.arguments;
+    return out;
+  }
+
+  function listPrompts() {
+    return { prompts: [...promptRegistry.values()].map(shapePrompt) };
+  }
+
+  function getPrompt(params) {
+    const name = params && params.name;
+    const prompt = name && promptRegistry.get(name);
+    if (!prompt) {
+      const err = new Error(`unknown prompt: ${name}`);
+      err.rpcCode = ERROR.INVALID_PARAMS;
+      throw err;
+    }
+    return { description: prompt.description || '', messages: prompt.buildMessages((params && params.arguments) || {}) };
+  }
+
+  async function listAvailableTools() {
+    const out = [];
+    for (const t of registry.values()) {
+      if (typeof t.available === 'function') {
+        let visible = true;
+        try {
+          visible = (await t.available()) !== false;
+        } catch {
+          visible = true;
+        }
+        if (!visible) continue;
+      }
+      out.push(shapeTool(t));
+    }
+    return { tools: out };
+  }
+
+  async function callTool(params) {
+    const name = params && params.name;
+    const tool = name && registry.get(name);
+    if (!tool) {
+      const err = new Error(`unknown tool: ${name}`);
+      err.rpcCode = ERROR.INVALID_PARAMS;
+      throw err;
+    }
+    const args = (params && params.arguments) || {};
+    // Optional per-call hook (auth-agnostic): the MCP server is long-lived, so this is where the email session's hub JWT gets refreshed before each tool runs.
+    if (typeof beforeCall === 'function') {
+      try { await beforeCall(name); } catch { /* hook must never break a tool call */ }
+    }
+    try {
+      const value = await tool.handler(args, { elicit, elicitation: !!send && canElicitForm() });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        isError: false,
+      };
+    } catch (e) {
+      return {
+        content: [{ type: 'text', text: `${name} tool error: ${e && e.message ? e.message : String(e)}` }],
+        isError: true,
+      };
+    }
+  }
+
+  async function handleMessage(msg) {
+    if (isResponse(msg)) {
+      settle(msg);
+      return null;
+    }
+    if (!msg || msg.jsonrpc !== JSONRPC || typeof msg.method !== 'string') {
+      if (isNotification(msg)) return null;
+      return errorResponse(msg && msg.id, ERROR.INVALID_REQUEST, 'invalid JSON-RPC request');
+    }
+
+    const { method, id } = msg;
+
+    if (method.startsWith('notifications/')) {
+      return null;
+    }
+
+    try {
+      switch (method) {
+        case 'initialize': {
+          const requested = msg.params && msg.params.protocolVersion;
+          clientCapabilities = (msg.params && msg.params.capabilities) || {};
+          if (typeof onInitialize === 'function') {
+            try { onInitialize({ clientInfo: (msg.params && msg.params.clientInfo) || {} }); } catch { /* never breaks the handshake */ }
+          }
+          // One line per connection on stderr (never stdout: it carries JSON-RPC), so the host's
+          // declared elicitation shape and the resulting decision are visible in the MCP log.
+          process.stderr.write(`  [mcp] initialize elicitation=${JSON.stringify(clientCapabilities.elicitation)} -> elicit=${canElicitForm()}\n`);
+          const text = typeof instructions === 'function' ? instructions({ elicitation: canElicitForm() }) : instructions;
+          return resultResponse(id, {
+            protocolVersion: requested || advertisedVersion,
+            capabilities: {
+              tools: { listChanged: false },
+              ...(promptRegistry.size ? { prompts: { listChanged: false } } : {}),
+            },
+            serverInfo: {
+              name: serverInfo.name || 'shakers-mcp',
+              version: serverInfo.version || '0.0.0',
+            },
+            // Server-level guidance the client keeps in the model's context even
+            // when it loads tool schemas lazily (Claude Code defers MCP tools).
+            ...(typeof text === 'string' && text ? { instructions: text } : {}),
+          });
+        }
+        case 'ping':
+          return resultResponse(id, {});
+        case 'tools/list':
+          return resultResponse(id, await listAvailableTools());
+        case 'tools/call':
+          return resultResponse(id, await callTool(msg.params));
+        case 'prompts/list':
+          return resultResponse(id, listPrompts());
+        case 'prompts/get':
+          return resultResponse(id, getPrompt(msg.params));
+        default:
+          if (isNotification(msg)) return null;
+          return errorResponse(id, ERROR.METHOD_NOT_FOUND, `method not found: ${method}`);
+      }
+    } catch (e) {
+      if (isNotification(msg)) return null;
+      const code = (e && e.rpcCode) || ERROR.INTERNAL;
+      return errorResponse(id, code, e && e.message ? e.message : 'internal error');
+    }
+  }
+
+  function start({ input = process.stdin, output = process.stdout, onError } = {}) {
+    const rl = readline.createInterface({ input, crlfDelay: Infinity });
+    const write = (obj) => output.write(`${JSON.stringify(obj)}\n`);
+    send = write;
+    rl.on('close', () => {
+      send = null;
+      rejectPending('the client closed the connection');
+    });
+
+    rl.on('line', async (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch {
+        write(errorResponse(null, ERROR.PARSE, 'parse error: invalid JSON'));
+        return;
+      }
+      try {
+        const response = await handleMessage(msg);
+        if (response) write(response);
+      } catch (e) {
+        if (onError) onError(e);
+        if (!isNotification(msg)) {
+          write(errorResponse(msg.id, ERROR.INTERNAL, e && e.message ? e.message : 'internal error'));
+        }
+      }
+    });
+
+    return rl;
+  }
+
+  return { handleMessage, listTools, listAvailableTools, callTool, start };
+}
+
+module.exports = { createMcpServer, ERROR, DEFAULT_PROTOCOL_VERSION };

package/src/mcp-show-project-tools.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// MCP: detail of one Position/Project (Find Positions detail view).
+
+const SHOW_PROJECT_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Position id (UUID or legacy Mongo id) — an internal handle from a prior list; never shown to the talent.' },
+  },
+  required: ['id'],
+};
+
+function makeShowProjectTools(deps = {}) {
+  const {
+    fetchPositionDetail = (opts) => require('./show-project-client').fetchPositionDetail({}, 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 (show_project is session-gated).');
+    }
+    return session;
+  };
+
+  async function showProject(args = {}) {
+    const session = requireLoginSession();
+    const positionId = typeof args.id === 'string' ? args.id.trim() : null;
+    if (!positionId) return { ok: false, reason: 'no-id' };
+    const res = await fetchPositionDetail({ hubAccessToken: session.hubAccessToken, positionId });
+    if (!res.ok) return { ok: false, reason: res.reason };
+    return { ok: true, position: res.position, redirectUrl: res.redirectUrl };
+  }
+
+  return [
+    {
+      name: 'show_project',
+      title: 'See a project',
+      description: 'Shows the full details of one Shakers project.',
+      guidance: "Get the full detail of one Position/Project available to the talent (Shakers Find Positions detail): title, parent project, company, budget, work mode, required skills/languages, description, goals, FAQs, and the talent's saved/applied/canApply state. Requires an active session and the position id. The `id` (and any positionId/projectId in the result) is an INTERNAL handle for calling tools — NEVER show or mention it to the talent; refer to the project by its title/company.",
+      inputSchema: SHOW_PROJECT_SCHEMA,
+      handler: showProject,
+    },
+  ];
+}
+
+module.exports = {
+  makeShowProjectTools,
+  SHOW_PROJECT_SCHEMA,
+};

package/src/mcp-signup-client.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const { postJsonWithTimeout, postMultipartWithTimeout } = require('./backend-request');
+
+// Hub calls of the MCP sign-up (ticket 39540): public sign-up + claim code, the signed-in talent's import status, and the one-time web login token.
+
+const SIGNUP_TIMEOUT_MS = 60000;
+const DEFAULT_TIMEOUT_MS = 15000;
+
+// Hub's coded errors on the sign-up, verified against the works-ai exception filter (hub MR !2198); none says whether an account exists.
+const CODE_TO_REASON = {
+  MISSING_SOURCE: 'missing-source',
+  INVALID_CV: 'invalid-cv',
+  INVALID_LINKEDIN_URL: 'invalid-linkedin-url',
+  RATE_LIMITED: 'rate-limited',
+};
+const IMPORT_SOURCES = ['linkedin', 'cv'];
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(res) {
+  const body = parseJson(res.raw);
+  const code = body && typeof body.code === 'string' ? body.code : null;
+  return { ok: false, reason: (code && CODE_TO_REASON[code]) || `http-${res.status}`, status: res.status };
+}
+
+function envelopeData(raw) {
+  const json = parseJson(raw);
+  return json && json.status === 'OK' && json.data && typeof json.data === 'object' ? json.data : null;
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+async function requestMcpSignup(
+  { linkedinUrl, cv, email, firstName, lastName, userQuery, language } = {},
+  { endpoint, timeoutMs = SIGNUP_TIMEOUT_MS } = {},
+) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const fields = {
+    linkedinUrl: nonEmpty(linkedinUrl),
+    email: nonEmpty(email),
+    firstName: nonEmpty(firstName),
+    lastName: nonEmpty(lastName),
+    userQuery: nonEmpty(userQuery),
+    language: nonEmpty(language),
+    file: cv && Buffer.isBuffer(cv.data) ? cv : undefined,
+  };
+  let res;
+  try {
+    res = await postMultipartWithTimeout(endpoint, fields, timeoutMs, 'POST');
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return failure(res);
+  const data = envelopeData(res.raw);
+  if (!data || typeof data.claimCode !== 'string' || !data.claimCode) return { ok: false, reason: 'bad-response' };
+  return { ok: true, claimCode: data.claimCode, claimCodeExpiresAt: data.claimCodeExpiresAt || null };
+}
+
+// { state: running | done | failed, sources: { linkedin?, cv? } }, the shape signup_status reports.
+function importStateOf(data) {
+  const status = data.profileImportStatus;
+  const reported = Array.isArray(data.sources) ? data.sources : [];
+  const sources = {};
+  for (const entry of reported) {
+    if (!entry || !IMPORT_SOURCES.includes(entry.source) || !['imported', 'failed'].includes(entry.status)) continue;
+    const failed = entry.status === 'failed';
+    sources[entry.source] = { state: failed ? 'failed' : 'done', ...(failed && typeof entry.code === 'string' ? { code: entry.code } : {}) };
+  }
+  if (status === 'PENDING' || status === 'RUNNING') return { state: 'running', sources: {} };
+  if (status === 'FAILED' || status === 'SKIPPED') return { state: 'failed', code: data.errorCode || null, sources };
+  if (status === 'DONE') return { state: 'done', sources };
+  return { state: 'none', sources: {} };
+}
+
+async function requestMyImportStatus({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-session' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, { Authorization: `Bearer ${hubAccessToken}` });
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}`, status: res.status };
+  const data = envelopeData(res.raw);
+  if (!data) return { ok: false, reason: 'bad-response' };
+  return { ok: true, ...importStateOf(data) };
+}
+
+// better-auth reads the session from the cookie (email sign-in) or the Bearer session token (device flow).
+async function requestOneTimeToken({ cookie = null, sessionToken = null } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  const headers = {};
+  if (cookie) headers.Cookie = cookie;
+  else if (sessionToken) headers.Authorization = `Bearer ${sessionToken}`;
+  else return { ok: false, reason: 'no-session' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, headers);
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: `http-${res.status}`, status: res.status };
+  const body = parseJson(res.raw);
+  const token = body && (typeof body.token === 'string' ? body.token : (body.data && body.data.token));
+  return typeof token === 'string' && token ? { ok: true, token } : { ok: false, reason: 'bad-response' };
+}
+
+module.exports = { requestMcpSignup, requestMyImportStatus, requestOneTimeToken, CODE_TO_REASON };