@recruiter-tools/mcp 1.0.0

package/dist/client.js

@@ -0,0 +1,46 @@
+/**
+ * HTTP client for candidate-routing API.
+ * Auth: Bearer token — reads dynamically from token-store so login() takes effect
+ * immediately without restarting the server.
+ */
+import { getToken } from './token-store.js';
+export class CRClient {
+    baseUrl;
+    constructor(baseUrl, _token) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+    async get(path) {
+        return this.request('GET', path);
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async delete(path) {
+        return this.request('DELETE', path);
+    }
+    async request(method, path, body) {
+        const url = this.baseUrl + path;
+        const token = getToken();
+        if (!token) {
+            throw new Error('Not authenticated. Call login(email, password) to authenticate.');
+        }
+        const headers = {
+            Authorization: `Bearer ${token}`,
+        };
+        const init = { method, headers, signal: AbortSignal.timeout(30_000) };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const res = await fetch(url, init);
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`${method} ${path} → ${res.status}: ${text.slice(0, 500)}`);
+        }
+        const ct = res.headers.get('content-type') ?? '';
+        if (ct.includes('application/json')) {
+            return res.json();
+        }
+        return res.text();
+    }
+}

package/dist/index.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+/**
+ * recruiter-mcp — MCP server entry point.
+ *
+ * Startup sequence:
+ * 1. Register login/whoami tools (work without a token)
+ * 2. Read services.json — list of backend services
+ * 3. For each service: try to fetch /api/mcp/manifest and register tools dynamically
+ * 4. If manifest unavailable and fallback="static" — register hardcoded tools
+ * 5. Connect MCP transport
+ */
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { CRClient } from './client.js';
+import { registerFromManifest } from './registry.js';
+import { getToken, setToken } from './token-store.js';
+// Static tool registrations (fallback)
+import { registerCandidateTools } from './tools/candidates.js';
+import { registerJobTools } from './tools/jobs.js';
+import { registerHHTools } from './tools/hh.js';
+import { registerLinkedInTools } from './tools/linkedin.js';
+// Neon-backed tools (always registered if RECRUITER_NEON_URL is set)
+import { registerNeonTools } from './tools/neon.js';
+const servicesPath = new URL('../services.json', import.meta.url);
+const servicesConfig = JSON.parse(readFileSync(servicesPath, 'utf-8'));
+// ── Env ───────────────────────────────────────────────────────
+const crBaseUrl = process.env.CR_BASE_URL ?? 'https://recruiter-assistant.com';
+const agentUrl = (process.env.RECRUITER_AGENT_URL ?? 'https://agent.recruiter-assistant.com').replace(/\/$/, '');
+// ── Create MCP server ─────────────────────────────────────────
+const server = new McpServer({
+    name: 'recruiter-mcp',
+    version: '1.0.0',
+});
+let totalTools = 0;
+// ── login tool ────────────────────────────────────────────────
+// Works without a pre-configured token. Call this first to authenticate.
+server.tool('login', 'Authenticate with your recruiter account. Call this at the start of a session if no token is configured. Returns your MCP token and the exact config snippet to paste into Claude Code or Codex settings.', {
+    email: z.string().describe('Your recruiter account email'),
+    password: z.string().describe('Your recruiter account password'),
+    label: z.string().optional().describe('Label for this token, e.g. "Claude Code", "Codex"'),
+}, async ({ email, password, label }) => {
+    const text = (msg) => ({ content: [{ type: 'text', text: msg }] });
+    // Step 1 — get JWT from recruiting-agent
+    let jwt;
+    let userName;
+    try {
+        const res = await fetch(`${agentUrl}/api/auth/login`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email, password }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            const err = await res.text().catch(() => '');
+            return text(`Login failed (${res.status}): ${err || 'invalid credentials'}`);
+        }
+        const data = await res.json();
+        jwt = data.token;
+        userName = data.user.name;
+    }
+    catch (err) {
+        return text(`Login error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Step 2 — bootstrap an MCP token via recruiting-agent
+    const tokenLabel = label ?? `Claude Code ${new Date().toISOString().slice(0, 10)}`;
+    let bootstrap;
+    try {
+        const res = await fetch(`${agentUrl}/api/mcp/bootstrap`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${jwt}`,
+            },
+            body: JSON.stringify({ client_type: 'claude-code', label: tokenLabel }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            const err = await res.text().catch(() => '');
+            return text(`Bootstrap failed (${res.status}): ${err}`);
+        }
+        bootstrap = await res.json();
+    }
+    catch (err) {
+        return text(`Bootstrap error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Step 3 — store token in memory for this session
+    setToken(bootstrap.token);
+    const jobLines = bootstrap.accessible_jobs === '*'
+        ? '  (all jobs — admin)'
+        : bootstrap.accessible_jobs
+            .map(j => `  • ${j.slug} — ${j.title}`)
+            .join('\n');
+    return text([
+        `Logged in as ${userName} (${bootstrap.user.role})`,
+        `Token ID: ${bootstrap.token_id} | Expires: ${bootstrap.expires_at ?? 'never'}`,
+        '',
+        'Accessible jobs:',
+        jobLines,
+        '',
+        'Token is active for this session.',
+        'To persist across restarts, add to your config:',
+        '',
+        '── Claude Code (~/.claude/settings.json) ──',
+        `"CR_SESSION_TOKEN": "${bootstrap.token}"`,
+        '',
+        '── Codex (~/.codex/config.toml) ──',
+        `[mcp_servers.recruiter-mcp.env]`,
+        `CR_SESSION_TOKEN = "${bootstrap.token}"`,
+    ].join('\n'));
+});
+totalTools += 1;
+// ── whoami tool ───────────────────────────────────────────────
+server.tool('whoami', 'Show current user identity and accessible jobs. Call this at the start of a session to confirm which recruiter account is active. If not authenticated, call login(email, password) first.', {}, async () => {
+    const token = getToken();
+    if (!token) {
+        return { content: [{ type: 'text', text: 'Not authenticated. Call login(email, password) to authenticate.' }] };
+    }
+    const res = await fetch(`${crBaseUrl.replace(/\/$/, '')}/api/tokens/whoami`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        const t = await res.text().catch(() => '');
+        return { content: [{ type: 'text', text: `Error ${res.status}: ${t}` }] };
+    }
+    const data = await res.json();
+    const jobLines = data.accessible_jobs === '*'
+        ? '  (all jobs — admin)'
+        : data.accessible_jobs.map(j => `  • ${j.slug} — ${j.title}`).join('\n');
+    return { content: [{ type: 'text', text: `Logged in as: ${data.user_id} (${data.role})\n\nAccessible jobs:\n${jobLines}` }] };
+});
+totalTools += 1;
+process.stderr.write('[recruiter-mcp] login + whoami tools registered\n');
+// ── Register tools from all services ──────────────────────────
+for (const svc of servicesConfig.services) {
+    const result = await registerFromManifest(server, svc);
+    if (result) {
+        process.stderr.write(`[recruiter-mcp] ${result.service} v${result.version}: ${result.toolCount} tools` +
+            (result.playbookCount ? `, ${result.playbookCount} playbooks` : '') +
+            ` (dynamic)\n`);
+        totalTools += result.toolCount;
+    }
+    else if (svc.fallback === 'static') {
+        const baseUrl = process.env[svc.env.base_url];
+        if (!baseUrl) {
+            process.stderr.write(`[recruiter-mcp] ${svc.name}: skipped — missing ${svc.env.base_url}\n`);
+            continue;
+        }
+        const client = new CRClient(baseUrl);
+        registerCandidateTools(server, client);
+        registerJobTools(server, client);
+        registerHHTools(server, client);
+        registerLinkedInTools(server, client);
+        process.stderr.write(`[recruiter-mcp] ${svc.name}: 27 tools (static fallback)\n`);
+        totalTools += 27;
+    }
+    else {
+        process.stderr.write(`[recruiter-mcp] ${svc.name}: skipped — no manifest, no fallback\n`);
+    }
+}
+// ── Register Neon tools (independent of CR services) ─────────
+const neonToolCount = registerNeonTools(server);
+totalTools += neonToolCount;
+// ── Connect transport ─────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[recruiter-mcp] Server started (${totalTools} tools)\n`);

package/dist/registry.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { getToken } from './token-store.js';
+// ── JSON Schema → Zod conversion ─────────────────────────────
+function paramToZod(param) {
+    let schema;
+    switch (param.type) {
+        case 'string':
+            schema = param.enum
+                ? z.enum(param.enum)
+                : z.string();
+            break;
+        case 'number':
+            schema = z.number();
+            break;
+        case 'boolean':
+            schema = z.boolean();
+            break;
+        case 'object':
+            schema = z.record(z.unknown());
+            break;
+        case 'array':
+            schema = z.array(param.items?.type === 'number' ? z.number() : z.string());
+            break;
+        default:
+            schema = z.unknown();
+    }
+    if (param.description) {
+        schema = schema.describe(param.description);
+    }
+    if (!param.required) {
+        schema = schema.optional();
+    }
+    return schema;
+}
+function buildZodSchema(parameters) {
+    const shape = {};
+    for (const [key, param] of Object.entries(parameters)) {
+        shape[key] = paramToZod(param);
+    }
+    return shape;
+}
+function buildAuthHeaders(auth) {
+    switch (auth.type) {
+        case 'cookie':
+            return { Cookie: `${auth.cookieName ?? 'session'}=${auth.token}` };
+        case 'bearer':
+            return { Authorization: `Bearer ${auth.token}` };
+        case 'header':
+            return { [auth.headerName ?? 'X-API-Key']: auth.token };
+    }
+}
+async function proxyRequest(baseUrl, auth, endpoint, params) {
+    // Token store takes precedence over the static auth config captured at registration
+    const liveToken = getToken();
+    if (!liveToken) {
+        throw new Error('Not authenticated. Call login(email, password) to authenticate.');
+    }
+    const resolvedAuth = { ...auth, token: liveToken };
+    // 1. Substitute path params
+    let path = endpoint.path;
+    for (const p of endpoint.path_params ?? []) {
+        path = path.replace(`{${p}}`, encodeURIComponent(String(params[p])));
+    }
+    // 2. Build query string
+    const qp = new URLSearchParams();
+    for (const p of endpoint.query_params ?? []) {
+        if (params[p] !== undefined) {
+            qp.set(p, String(params[p]));
+        }
+    }
+    const qs = qp.toString();
+    const url = `${baseUrl}${path}${qs ? '?' + qs : ''}`;
+    // 3. Build body
+    const bodyKeys = endpoint.body_params;
+    let body;
+    if (bodyKeys && (endpoint.method === 'POST' || endpoint.method === 'PUT')) {
+        body = {};
+        for (const p of bodyKeys) {
+            if (params[p] !== undefined) {
+                body[p] = params[p];
+            }
+        }
+    }
+    else if (!bodyKeys &&
+        (endpoint.method === 'POST' || endpoint.method === 'PUT')) {
+        // No explicit body_params — send all non-path/non-query params as body
+        const pathSet = new Set(endpoint.path_params ?? []);
+        const querySet = new Set(endpoint.query_params ?? []);
+        body = {};
+        for (const [k, v] of Object.entries(params)) {
+            if (!pathSet.has(k) && !querySet.has(k) && v !== undefined) {
+                body[k] = v;
+            }
+        }
+        if (Object.keys(body).length === 0)
+            body = undefined;
+    }
+    // 4. Make request
+    const headers = {
+        ...buildAuthHeaders(resolvedAuth),
+    };
+    const init = {
+        method: endpoint.method,
+        headers,
+        signal: AbortSignal.timeout(30_000),
+    };
+    if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`${endpoint.method} ${path} → ${res.status}: ${text.slice(0, 500)}`);
+    }
+    const ct = res.headers.get('content-type') ?? '';
+    if (ct.includes('application/json')) {
+        return res.json();
+    }
+    return res.text();
+}
+// ── Main: fetch manifest & register tools ─────────────────────
+function json(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export async function registerFromManifest(server, svcConfig) {
+    const baseUrl = process.env[svcConfig.env.base_url];
+    const token = process.env[svcConfig.env.token];
+    if (!baseUrl || !token) {
+        process.stderr.write(`[registry] Skipping ${svcConfig.name}: missing env ${svcConfig.env.base_url} or ${svcConfig.env.token}\n`);
+        return null;
+    }
+    const manifestUrl = `${baseUrl}${svcConfig.manifest_path}`;
+    let manifest;
+    try {
+        const res = await fetch(manifestUrl, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            throw new Error(`${res.status} ${res.statusText}`);
+        }
+        manifest = (await res.json());
+    }
+    catch (err) {
+        process.stderr.write(`[registry] Failed to fetch manifest from ${svcConfig.name} (${manifestUrl}): ${err}\n`);
+        return null;
+    }
+    // Build auth config
+    const authToken = process.env[manifest.auth.env_var] ?? token;
+    const authCfg = {
+        type: manifest.auth.type,
+        cookieName: manifest.auth.cookie_name,
+        headerName: manifest.auth.header_name,
+        token: authToken,
+    };
+    const svcBaseUrl = process.env[manifest.base_url_env] ?? baseUrl;
+    // Register tools
+    for (const tool of manifest.tools) {
+        let description = tool.description;
+        if (tool.deprecated) {
+            description = `[DEPRECATED: ${tool.deprecated_message ?? 'use newer alternative'}] ${description}`;
+        }
+        const zodShape = buildZodSchema(tool.parameters);
+        server.tool(tool.name, description, zodShape, async (params) => {
+            return json(await proxyRequest(svcBaseUrl, authCfg, tool.endpoint, params));
+        });
+    }
+    // Register playbooks as a resource (list_playbooks meta-tool)
+    if (manifest.playbooks && manifest.playbooks.length > 0) {
+        const playbooks = manifest.playbooks;
+        server.tool(`${manifest.service}_playbooks`, `List available playbooks for ${manifest.service}. Playbooks describe multi-step workflows.`, {}, async () => {
+            return json(playbooks.map((p) => ({
+                name: p.name,
+                description: p.description,
+                steps: p.steps,
+                context: p.context,
+            })));
+        });
+    }
+    return {
+        service: manifest.service,
+        toolCount: manifest.tools.length,
+        playbookCount: manifest.playbooks?.length ?? 0,
+        version: manifest.version,
+    };
+}

package/dist/token-store.js

@@ -0,0 +1,16 @@
+/**
+ * Mutable token store — holds the active Bearer token for the current session.
+ *
+ * Initialized from env at startup; can be overwritten by the `login` tool
+ * so that auth works without restarting the MCP server.
+ */
+let currentToken = process.env.CR_SESSION_TOKEN ?? null;
+export function getToken() {
+    return currentToken;
+}
+export function setToken(token) {
+    currentToken = token;
+}
+export function hasToken() {
+    return Boolean(currentToken);
+}

package/dist/tools/candidates.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function registerCandidateTools(server, client) {
+    // ── list_candidates ──────────────────────────────────────
+    server.tool('list_candidates', 'List candidates with optional filters by job, status, name/email search, and fact values. Returns candidate list with AI scores.', {
+        job_slug: z.string().optional().describe('Filter by job slug'),
+        status: z.string().optional().describe('Filter by status (e.g. NEW, SCREENING, INTERVIEW_PASSED)'),
+        search: z.string().optional().describe('Search by name or email (supports cyrillic)'),
+        limit: z.number().optional().describe('Max results (default 500, max 2000)'),
+    }, async ({ job_slug, status, search, limit }) => {
+        const params = new URLSearchParams();
+        if (job_slug)
+            params.set('job_slug', job_slug);
+        if (status)
+            params.set('status', status);
+        if (search)
+            params.set('search', search);
+        if (limit)
+            params.set('limit', String(limit));
+        const qs = params.toString();
+        return json(await client.get(`/api/candidates${qs ? '?' + qs : ''}`));
+    });
+    // ── get_candidate ────────────────────────────────────────
+    server.tool('get_candidate', 'Get full candidate details including messages. Returns candidate object and message history.', {
+        candidate_id: z.number().describe('Candidate ID'),
+    }, async ({ candidate_id }) => {
+        return json(await client.get(`/api/candidates/${candidate_id}`));
+    });
+    // ── get_candidate_dialog ─────────────────────────────────
+    server.tool('get_candidate_dialog', 'Get candidate conversation log formatted for agent consumption. Separates conversation, interview transcript, resume, and parsed facts.', {
+        candidate_id: z.number().describe('Candidate ID'),
+    }, async ({ candidate_id }) => {
+        return json(await client.get(`/api/candidates/${candidate_id}/dialog`));
+    });
+    // ── get_candidate_status ─────────────────────────────────
+    server.tool('get_candidate_status', 'Get candidate status info: current status, available actions (reject, send-interview, send-message, etc.), screening progress, AI score, timeline.', {
+        candidate_id: z.number().describe('Candidate ID'),
+    }, async ({ candidate_id }) => {
+        return json(await client.get(`/api/candidates/${candidate_id}/status-info`));
+    });
+    // ── send_message ─────────────────────────────────────────
+    server.tool('send_message', 'Send a message to a candidate through their channel (email, hh.ru, or LinkedIn). Supports delayed sending.', {
+        candidate_id: z.number().describe('Candidate ID'),
+        message: z.string().describe('Message text to send'),
+        delay_minutes: z.number().optional().describe('Delay in minutes before sending (default: job setting or 15)'),
+    }, async ({ candidate_id, message, delay_minutes }) => {
+        const body = { message };
+        if (delay_minutes !== undefined)
+            body.delay_minutes = delay_minutes;
+        return json(await client.post(`/api/candidates/${candidate_id}/send-message`, body));
+    });
+    // ── advance_candidate ────────────────────────────────────
+    server.tool('advance_candidate', 'Advance or reject a candidate. Actions: reject, send-interview, resend-interview, skip-to-homework, send-homework. Check get_candidate_status for available actions first.', {
+        candidate_id: z.number().describe('Candidate ID'),
+        action: z.enum(['reject', 'send-interview', 'resend-interview', 'skip-to-homework', 'send-homework'])
+            .describe('Action to perform'),
+    }, async ({ candidate_id, action }) => {
+        return json(await client.post(`/api/candidates/${candidate_id}/advance`, { action }));
+    });
+    // ── add_candidate ────────────────────────────────────────
+    server.tool('add_candidate', 'Manually add a new candidate to a job. Returns created candidate.', {
+        email: z.string().describe('Candidate email'),
+        name: z.string().optional().describe('Candidate name'),
+        job_slug: z.string().describe('Job slug to assign'),
+        status: z.string().optional().describe('Initial status (default: NEW)'),
+    }, async ({ email, name, job_slug, status }) => {
+        const body = { email, job_slug };
+        if (name)
+            body.name = name;
+        if (status)
+            body.status = status;
+        return json(await client.post('/api/candidates', body));
+    });
+    // ── change_status ────────────────────────────────────────
+    server.tool('change_status', 'Change status for one or more candidates (bulk operation). Use advance_candidate for pipeline actions instead.', {
+        candidate_ids: z.array(z.number()).describe('Array of candidate IDs'),
+        new_status: z.string().describe('New status to set'),
+    }, async ({ candidate_ids, new_status }) => {
+        return json(await client.post('/api/execute', {
+            action_type: 'STATUS_CHANGE',
+            candidate_ids,
+            new_status,
+        }));
+    });
+    // ── search_candidates ────────────────────────────────────
+    server.tool('search_candidates', 'AI-powered semantic search across all candidate profiles using Gemini. Returns matching candidate IDs. Use for complex queries like "candidates with 5+ years of React experience".', {
+        query: z.string().describe('Natural language search query'),
+    }, async ({ query }) => {
+        return json(await client.post('/api/search-ai', { query }));
+    });
+    // ── generate_profile ─────────────────────────────────────
+    server.tool('generate_profile', 'Trigger generation of a final candidate profile (summary document). Only works for candidates with enough data.', {
+        candidate_id: z.number().describe('Candidate ID'),
+    }, async ({ candidate_id }) => {
+        return json(await client.post(`/api/candidates/${candidate_id}/generate-profile`));
+    });
+}

package/dist/tools/hh.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function registerHHTools(server, client) {
+    // ── hh_status ────────────────────────────────────────────
+    server.tool('hh_status', 'Check hh.ru connection status: connected/disconnected, employer info, token expiration.', {}, async () => {
+        return json(await client.get('/api/hh/status'));
+    });
+    // ── hh_list_vacancies ────────────────────────────────────
+    server.tool('hh_list_vacancies', 'List active vacancies on hh.ru for the connected employer account.', {}, async () => {
+        return json(await client.get('/api/hh/vacancies'));
+    });
+    // ── hh_sync ──────────────────────────────────────────────
+    server.tool('hh_sync', 'Trigger full hh.ru sync: fetch new responses, process must-have replies, interview follow-ups, channel replies, QA replies, homework replies, resume mismatch replies, screening replies.', {}, async () => {
+        return json(await client.post('/api/hh/sync'));
+    });
+    // ── hh_reprocess_new ─────────────────────────────────────
+    server.tool('hh_reprocess_new', 'Re-process NEW hh.ru candidates: auto-advance those above score threshold, send mismatch to the rest. Useful after changing thresholds.', {
+        job_slug: z.string().describe('Job slug to reprocess'),
+        limit: z.number().optional().describe('Max candidates to process (default: 20)'),
+    }, async ({ job_slug, limit }) => {
+        const body = { job_slug };
+        if (limit !== undefined)
+            body.limit = limit;
+        return json(await client.post('/api/hh/reprocess-new', body));
+    });
+    // ── hh_vacancy_maps ──────────────────────────────────────
+    server.tool('hh_vacancy_maps', 'Get all hh.ru vacancy → job_slug mappings. Shows which hh.ru vacancies are linked to which jobs.', {}, async () => {
+        return json(await client.get('/api/hh/vacancy-maps'));
+    });
+    // ── hh_create_vacancy_map ────────────────────────────────
+    server.tool('hh_create_vacancy_map', 'Create or update a mapping between an hh.ru vacancy and a job_slug. Required to route hh.ru responses to the correct job.', {
+        hh_vacancy_id: z.string().describe('HH.ru vacancy ID'),
+        job_slug: z.string().describe('Job slug to map to'),
+        hh_vacancy_name: z.string().optional().describe('HH vacancy name (for display)'),
+    }, async ({ hh_vacancy_id, job_slug, hh_vacancy_name }) => {
+        const body = { hh_vacancy_id, job_slug };
+        if (hh_vacancy_name)
+            body.hh_vacancy_name = hh_vacancy_name;
+        return json(await client.post('/api/hh/vacancy-map', body));
+    });
+    // ── hh_create_draft ──────────────────────────────────────
+    server.tool('hh_create_draft', 'Create a vacancy draft on hh.ru. Pass the draft data as a JSON object following hh.ru API format.', {
+        draft_data: z.record(z.unknown()).describe('Draft vacancy data in hh.ru API format'),
+    }, async ({ draft_data }) => {
+        return json(await client.post('/api/hh/create-draft', draft_data));
+    });
+}

package/dist/tools/jobs.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function registerJobTools(server, client) {
+    // ── list_jobs ────────────────────────────────────────────
+    server.tool('list_jobs', 'List all jobs with their settings, sender/contact emails, and candidate counts.', {}, async () => {
+        return json(await client.get('/api/jobs'));
+    });
+    // ── get_job_settings ─────────────────────────────────────
+    server.tool('get_job_settings', 'Get full settings for a job: pipeline_template, FAQ reference, template_instruction, must-haves, interview config, homework, etc.', {
+        job_slug: z.string().describe('Job slug'),
+    }, async ({ job_slug }) => {
+        return json(await client.get(`/api/jobs/${encodeURIComponent(job_slug)}/settings`));
+    });
+    // ── update_job_settings ──────────────────────────────────
+    server.tool('update_job_settings', 'Update job settings (partial update). Can update pipeline_template, template_instruction, must_haves, summary_fields, interview_language, homework_text, sender_email, and other fields.', {
+        job_slug: z.string().describe('Job slug'),
+        settings: z.record(z.unknown()).describe('Settings object (partial — only provided fields are updated)'),
+    }, async ({ job_slug, settings }) => {
+        return json(await client.post(`/api/jobs/${encodeURIComponent(job_slug)}/settings`, settings));
+    });
+    // ── deploy_job ───────────────────────────────────────────
+    server.tool('deploy_job', 'Deploy a job in one call: create/update job + settings + inbox mapping. Use this to set up a new job or reconfigure an existing one.', {
+        job_slug: z.string().describe('Job slug (URL-safe, lowercase, e.g. "frontend-engineer-1")'),
+        title: z.string().describe('Job title'),
+        sender_email: z.string().describe('Email to send from'),
+        contact_email: z.string().optional().describe('Contact email (default: vladimir+{slug}@skillset.ae)'),
+        inbox_email: z.string().optional().describe('Inbox email for receiving candidate replies'),
+        settings: z.record(z.unknown()).optional().describe('Job settings object'),
+    }, async ({ job_slug, title, sender_email, contact_email, inbox_email, settings }) => {
+        const body = { title, sender_email };
+        if (contact_email)
+            body.contact_email = contact_email;
+        if (inbox_email)
+            body.inbox_email = inbox_email;
+        if (settings)
+            body.settings = settings;
+        return json(await client.post(`/api/jobs/${encodeURIComponent(job_slug)}/deploy`, body));
+    });
+    // ── get_job_status ───────────────────────────────────────
+    server.tool('get_job_status', 'Get job pipeline statistics: candidate counts by status, last activity timestamps, pending outbox count.', {
+        job_slug: z.string().describe('Job slug'),
+    }, async ({ job_slug }) => {
+        return json(await client.get(`/api/jobs/${encodeURIComponent(job_slug)}/status`));
+    });
+    // ── get_job_funnel ───────────────────────────────────────
+    server.tool('get_job_funnel', 'Get candidate status funnel for a job — counts and percentages at each pipeline stage.', {
+        job_slug: z.string().describe('Job slug'),
+    }, async ({ job_slug }) => {
+        return json(await client.get(`/api/jobs/${encodeURIComponent(job_slug)}/funnel`));
+    });
+    // ── get_facts_schema ─────────────────────────────────────
+    server.tool('get_facts_schema', 'Get the summary_fields schema for a job with fill rates — shows which candidate facts are configured and how many candidates have each field filled.', {
+        job_slug: z.string().describe('Job slug'),
+    }, async ({ job_slug }) => {
+        return json(await client.get(`/api/jobs/${encodeURIComponent(job_slug)}/facts-schema`));
+    });
+}

package/dist/tools/linkedin.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function registerLinkedInTools(server, client) {
+    // ── linkedin_create_candidate ────────────────────────────
+    server.tool('linkedin_create_candidate', 'Create a candidate from a LinkedIn messaging thread. Automatically sends channel preference message via LinkedIn. Requires thread_url (from browser), job_slug, and name.', {
+        thread_url: z.string().describe('LinkedIn messaging thread URL'),
+        job_slug: z.string().describe('Job slug to assign'),
+        name: z.string().describe('Candidate full name'),
+        email: z.string().optional().describe('Candidate email (synthetic generated if not provided)'),
+        profile_url: z.string().optional().describe('LinkedIn profile URL'),
+    }, async ({ thread_url, job_slug, name, email, profile_url }) => {
+        const body = { thread_url, job_slug, name };
+        if (email)
+            body.email = email;
+        if (profile_url)
+            body.profile_url = profile_url;
+        return json(await client.post('/api/linkedin/create-candidate', body));
+    });
+    // ── linkedin_send_interview ──────────────────────────────
+    server.tool('linkedin_send_interview', 'Send an interview link to a LinkedIn candidate via their messaging thread. Only works for candidates with source=linkedin.', {
+        candidate_id: z.number().describe('Candidate ID (must be a LinkedIn candidate)'),
+    }, async ({ candidate_id }) => {
+        return json(await client.post('/api/linkedin/send-interview-link', { candidate_id }));
+    });
+    // ── linkedin_setup_hiring ────────────────────────────────
+    server.tool('linkedin_setup_hiring', 'Map a LinkedIn Job posting to a job_slug for automatic applicant sync from LinkedIn Hiring.', {
+        linkedin_job_id: z.string().describe('LinkedIn Job ID'),
+        job_slug: z.string().describe('Job slug to map to'),
+    }, async ({ linkedin_job_id, job_slug }) => {
+        return json(await client.post('/api/linkedin/hiring/setup', { linkedin_job_id, job_slug }));
+    });
+}

package/dist/tools/neon.js

@@ -0,0 +1,385 @@
+/**
+ * Neon-backed tools for recruiter-mcp.
+ *
+ * Tools registered here:
+ *   get_mart_catalog       — list all output_data_marts views with columns
+ *   query_mart             — query a mart view with optional filters
+ *   log_playbook_run_start — open a playbook run record, returns run id
+ *   log_playbook_run_complete — close a run with final status + summary
+ *   log_playbook_run_input — attach an input artifact to a run
+ *   log_playbook_run_output — attach an output artifact to a run
+ *   get_playbook_steps     — fetch steps for a playbook scenario
+ *
+ * MCP Prompt registered here:
+ *   recruiter_context      — returns AI rules + mart catalog summary
+ *
+ * Requires env: RECRUITER_NEON_URL
+ */
+import { neon } from '@neondatabase/serverless';
+import { z } from 'zod';
+// Known mart views with human descriptions (mirrors output_data_marts schema)
+const MART_VIEWS = [
+    {
+        name: 'mart_candidate_current_state',
+        description: 'Current state of each candidate across all jobs (status, source, contact info)',
+    },
+    {
+        name: 'mart_candidate_pipeline_state',
+        description: 'Candidate pipeline stage history and transitions',
+    },
+    {
+        name: 'mart_job_current_profile',
+        description: 'Current job profile: requirements, compensation, company context',
+    },
+    {
+        name: 'mart_job_current_publication_artifacts',
+        description: 'Published job texts (hh.ru, LinkedIn) and their status',
+    },
+    {
+        name: 'mart_job_pipeline_generation_context',
+        description: 'Context snapshot used to generate pipeline templates',
+    },
+    {
+        name: 'mart_job_pipeline_template_current',
+        description: 'Current pipeline template (goals list) for each job',
+    },
+    {
+        name: 'mart_job_profile_inputs',
+        description: 'Raw inputs used for job profile generation',
+    },
+    {
+        name: 'mart_playbook_run_inputs',
+        description: 'Input artifacts attached to each playbook run',
+    },
+    {
+        name: 'mart_playbook_run_outputs',
+        description: 'Output artifacts produced by each playbook run',
+    },
+    {
+        name: 'mart_playbook_runs',
+        description: 'History of all playbook runs: status, timing, result summary',
+    },
+];
+const MART_NAMES = MART_VIEWS.map((v) => v.name);
+export function registerNeonTools(server) {
+    const neonUrl = process.env.RECRUITER_NEON_URL;
+    if (!neonUrl) {
+        process.stderr.write('[recruiter-mcp] Neon tools skipped — RECRUITER_NEON_URL not set\n');
+        return 0;
+    }
+    const sql = neon(neonUrl);
+    // ── get_mart_catalog ────────────────────────────────────────────
+    server.tool('get_mart_catalog', 'List all available data mart views in output_data_marts with their descriptions and column names. Use this before query_mart to understand what fields are available.', {}, async () => {
+        const rows = await sql `
+        SELECT table_name, column_name, data_type
+        FROM information_schema.columns
+        WHERE table_schema = 'output_data_marts'
+          AND table_name LIKE 'mart_%'
+        ORDER BY table_name, ordinal_position
+      `;
+        const descMap = Object.fromEntries(MART_VIEWS.map((v) => [v.name, v.description]));
+        const catalog = {};
+        for (const row of rows) {
+            const name = row.table_name;
+            if (!catalog[name]) {
+                catalog[name] = {
+                    description: descMap[name] ?? '',
+                    columns: [],
+                };
+            }
+            catalog[name].columns.push({
+                name: row.column_name,
+                type: row.data_type,
+            });
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(catalog, null, 2) }],
+        };
+    });
+    // ── query_mart ─────────────────────────────────────────────────
+    server.tool('query_mart', 'Query a data mart view (read-only). Returns up to 100 rows. Always call get_mart_catalog first to know which columns exist.', {
+        mart: z.enum(MART_NAMES).describe('The mart view to query'),
+        filters: z
+            .record(z.string())
+            .optional()
+            .describe('Optional equality filters: { column: value }. Only simple = comparisons.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(50)
+            .describe('Max rows to return (default 50, max 100)'),
+    }, async ({ mart, filters, limit }) => {
+        // mart is already validated by z.enum — safe to interpolate
+        let query = `SELECT * FROM output_data_marts.${mart}`;
+        const params = [];
+        if (filters && Object.keys(filters).length > 0) {
+            const conditions = [];
+            for (const [col, val] of Object.entries(filters)) {
+                // Validate column name: lowercase letters, digits, underscores only
+                if (!/^[a-z_][a-z0-9_]*$/.test(col)) {
+                    throw new Error(`Invalid column name: ${col}`);
+                }
+                params.push(val);
+                conditions.push(`${col} = $${params.length}`);
+            }
+            query += ` WHERE ${conditions.join(' AND ')}`;
+        }
+        query += ` LIMIT ${limit ?? 50}`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rows = await sql(query, params);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ mart, row_count: rows.length, rows }, null, 2),
+                },
+            ],
+        };
+    });
+    // ── log_playbook_run_start ────────────────────────────────────
+    server.tool('log_playbook_run_start', 'Open a new playbook run record. Call at the start of any playbook execution. Returns playbook_run_id — pass it to all subsequent log_playbook_run_* calls.', {
+        playbook_template_id: z
+            .string()
+            .describe('Playbook scenario ID (matches management.playbook_scenarios.id)'),
+        tenant_id: z.string().optional().describe('Tenant identifier'),
+        data_layer_job_id: z.number().int().optional().describe('Canonical job ID'),
+        candidate_routing_candidate_id: z
+            .number()
+            .int()
+            .optional()
+            .describe('Candidate ID in candidate-routing (if applicable)'),
+        session_id: z.string().optional().describe('Current Claude Code session ID'),
+        triggered_by_user_id: z.string().optional().describe('User who triggered this run'),
+        run_payload_json: z
+            .record(z.unknown())
+            .optional()
+            .describe('Extra context to attach to the run record'),
+    }, async (params) => {
+        const rows = await sql `
+        INSERT INTO repository_recruiter_agent.recruiter_agent_playbook_runs
+          (tenant_id, playbook_template_id, data_layer_job_id,
+           candidate_routing_candidate_id, session_id, playbook_run_status,
+           triggered_by_user_id, playbook_run_started_at, run_payload_json, created_at)
+        VALUES (
+          ${params.tenant_id ?? null},
+          ${params.playbook_template_id},
+          ${params.data_layer_job_id ?? null},
+          ${params.candidate_routing_candidate_id ?? null},
+          ${params.session_id ?? null},
+          'running',
+          ${params.triggered_by_user_id ?? null},
+          NOW(),
+          ${params.run_payload_json ? JSON.stringify(params.run_payload_json) : null},
+          NOW()
+        )
+        RETURNING id
+      `;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ playbook_run_id: rows[0].id }),
+                },
+            ],
+        };
+    });
+    // ── log_playbook_run_complete ─────────────────────────────────
+    server.tool('log_playbook_run_complete', 'Close a playbook run with final status and result summary. Call after all actions are done.', {
+        playbook_run_id: z
+            .number()
+            .int()
+            .describe('Run ID returned by log_playbook_run_start'),
+        status: z
+            .enum(['completed', 'failed', 'cancelled'])
+            .describe('Final run status'),
+        run_result_summary: z
+            .string()
+            .optional()
+            .describe('Human-readable summary of what was done and the outcome'),
+    }, async ({ playbook_run_id, status, run_result_summary }) => {
+        await sql `
+        UPDATE repository_recruiter_agent.recruiter_agent_playbook_runs
+        SET playbook_run_status    = ${status},
+            playbook_run_completed_at = NOW(),
+            run_result_summary     = ${run_result_summary ?? null}
+        WHERE id = ${playbook_run_id}
+      `;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ ok: true, playbook_run_id, status }),
+                },
+            ],
+        };
+    });
+    // ── log_playbook_run_input ────────────────────────────────────
+    server.tool('log_playbook_run_input', 'Attach an input artifact to a playbook run (candidate profile, vacancy text, FAQ, etc.).', {
+        playbook_run_id: z.number().int().describe('Run ID from log_playbook_run_start'),
+        input_type: z
+            .string()
+            .describe('Type of input: "candidate_profile", "vacancy_text", "faq", "search_query", etc.'),
+        source_system: z
+            .string()
+            .optional()
+            .describe('Source system: "candidate-routing", "neon", "hh.ru", etc.'),
+        source_ref: z
+            .string()
+            .optional()
+            .describe('Reference ID or URL in the source system'),
+        input_payload_json: z
+            .record(z.unknown())
+            .optional()
+            .describe('Input content as JSON'),
+    }, async ({ playbook_run_id, input_type, source_system, source_ref, input_payload_json }) => {
+        const rows = await sql `
+        INSERT INTO repository_recruiter_agent.recruiter_agent_playbook_run_inputs
+          (playbook_run_id, input_type, source_system, source_ref, input_payload_json, created_at)
+        VALUES (
+          ${playbook_run_id},
+          ${input_type},
+          ${source_system ?? null},
+          ${source_ref ?? null},
+          ${input_payload_json ? JSON.stringify(input_payload_json) : null},
+          NOW()
+        )
+        RETURNING id
+      `;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ ok: true, id: rows[0].id }),
+                },
+            ],
+        };
+    });
+    // ── log_playbook_run_output ───────────────────────────────────
+    server.tool('log_playbook_run_output', 'Attach an output artifact to a playbook run (message sent, file created, status changed, etc.).', {
+        playbook_run_id: z.number().int().describe('Run ID from log_playbook_run_start'),
+        output_type: z
+            .string()
+            .describe('Type of output: "message_sent", "status_changed", "report_generated", "file_created", etc.'),
+        target_system: z
+            .string()
+            .optional()
+            .describe('Target system: "candidate-routing", "email", "hh.ru", etc.'),
+        target_ref: z
+            .string()
+            .optional()
+            .describe('Reference ID or URL in the target system'),
+        output_payload_json: z
+            .record(z.unknown())
+            .optional()
+            .describe('Output content or metadata as JSON'),
+    }, async ({ playbook_run_id, output_type, target_system, target_ref, output_payload_json }) => {
+        const rows = await sql `
+        INSERT INTO repository_recruiter_agent.recruiter_agent_playbook_run_outputs
+          (playbook_run_id, output_type, target_system, target_ref, output_payload_json, created_at)
+        VALUES (
+          ${playbook_run_id},
+          ${output_type},
+          ${target_system ?? null},
+          ${target_ref ?? null},
+          ${output_payload_json ? JSON.stringify(output_payload_json) : null},
+          NOW()
+        )
+        RETURNING id
+      `;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ ok: true, id: rows[0].id }),
+                },
+            ],
+        };
+    });
+    // ── get_playbook_steps ────────────────────────────────────────
+    server.tool('get_playbook_steps', 'Get the step-by-step execution plan for a playbook scenario from the management schema. Steps form a linked list via previous_step_id.', {
+        scenario_id: z
+            .string()
+            .describe('Playbook scenario ID (e.g. "candidate-statuses", "funnel")'),
+    }, async ({ scenario_id }) => {
+        const [scenario] = await sql `
+        SELECT id, name, trigger_description, keywords
+        FROM management.playbook_scenarios
+        WHERE id = ${scenario_id}
+      `;
+        if (!scenario) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: `Scenario '${scenario_id}' not found` }),
+                    },
+                ],
+            };
+        }
+        const steps = await sql `
+        SELECT id, name, previous_step_id, step_type, instruction_prompt
+        FROM management.playbook_steps
+        WHERE scenario_id = ${scenario_id}
+        ORDER BY created_at
+      `;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ scenario, steps }, null, 2),
+                },
+            ],
+        };
+    });
+    // ── MCP Prompt: recruiter_context ─────────────────────────────
+    server.prompt('recruiter_context', 'Load recruiter agent system context: AI rules and mart catalog. Use at the start of a session to orient the agent.', {}, async () => {
+        const [rules, martCols] = await Promise.all([
+            sql `
+          SELECT id, scope, rule
+          FROM repository_candidate_routing._ai_rules
+          ORDER BY scope DESC, id
+        `,
+            sql `
+          SELECT table_name, column_name
+          FROM information_schema.columns
+          WHERE table_schema = 'output_data_marts' AND table_name LIKE 'mart_%'
+          ORDER BY table_name, ordinal_position
+        `,
+        ]);
+        // Build mart summary (just table + column names, compact)
+        const martSummary = {};
+        for (const row of martCols) {
+            const t = row.table_name;
+            if (!martSummary[t])
+                martSummary[t] = [];
+            martSummary[t].push(row.column_name);
+        }
+        const rulesText = rules
+            .map((r) => `[${r.id}] (${r.scope}) ${r.rule}`)
+            .join('\n');
+        const martsText = Object.entries(martSummary)
+            .map(([name, cols]) => `${name}: ${cols.join(', ')}`)
+            .join('\n');
+        const text = `# Recruiter Agent Context
+
+## AI Rules
+${rulesText}
+
+## Available Mart Views (output_data_marts)
+${martsText}
+`;
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: { type: 'text', text },
+                },
+            ],
+        };
+    });
+    process.stderr.write('[recruiter-mcp] Neon tools registered (7 tools + recruiter_context prompt)\n');
+    return 7;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@recruiter-tools/mcp",
+  "version": "1.0.0",
+  "description": "MCP server connecting AI assistants (Claude Code, Codex, Cursor…) to recruiter-assistant.com recruiting tools",
+  "type": "module",
+  "bin": {
+    "recruiter-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "node --experimental-strip-types src/index.ts",
+    "build": "tsc && npm run postbuild",
+    "postbuild": "node -e \"const fs=require('fs');const f='dist/index.js';fs.writeFileSync(f,'#!/usr/bin/env node\\n'+fs.readFileSync(f,'utf8'));fs.chmodSync(f,0o755)\"",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "services.json"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@neondatabase/serverless": "^1.0.2",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/services.json

@@ -0,0 +1,14 @@
+{
+  "services": [
+    {
+      "name": "candidate-routing",
+      "manifest_url_env": "CR_BASE_URL",
+      "manifest_path": "/api/mcp/manifest",
+      "env": {
+        "base_url": "CR_BASE_URL",
+        "token": "CR_SESSION_TOKEN"
+      },
+      "fallback": "static"
+    }
+  ]
+}