@snokam/mcp-cvpartner 2.7.0 → 2.8.0

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+export declare function cvpartnerFetch<T>(endpoint: string, options?: RequestInit): Promise<T>;
+export declare function ok(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export interface CVPartnerUser {
+    user_id: string;
+    email: string;
+    name: string;
+    title?: {
+        no?: string;
+        int?: string;
+    };
+    telephone?: string;
+    office_name?: string;
+    deactivated: boolean;
+    default_cv_id?: string;
+}
+export interface CVSearchResult {
+    cv: {
+        user_id: string;
+        name: string;
+        email: string;
+        title?: string;
+        titles?: {
+            no?: string;
+            int?: string;
+        };
+        telephone?: string;
+        office_id?: string;
+        is_deactivated: boolean;
+    };
+    highlight?: string;
+}
+export declare function resolveCvId(user_id: string, cv_id?: string): Promise<string>;

package/dist/client.js

@@ -0,0 +1,44 @@
+const API_KEY = process.env.CVPARTNER_API_KEY;
+function resolveBaseUrl() {
+    const explicit = process.env.CV_PARTNER_BASE_URL;
+    if (explicit && explicit.trim()) {
+        return explicit.trim().replace(/\/+$/, "");
+    }
+    const org = process.env.CVPARTNER_ORG || "snokam";
+    return `https://${org}.cvpartner.com/api`;
+}
+const BASE_URL = resolveBaseUrl();
+export async function cvpartnerFetch(endpoint, options = {}) {
+    if (!API_KEY) {
+        throw new Error("CVPARTNER_API_KEY environment variable is required");
+    }
+    const path = endpoint.startsWith("/") ? endpoint : `/${endpoint}`;
+    const response = await fetch(`${BASE_URL}${path}`, {
+        ...options,
+        headers: {
+            Authorization: `Token token="${API_KEY}"`,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`CVPartner API error: ${response.status} - ${error || response.statusText}`);
+    }
+    const text = await response.text();
+    return (text ? JSON.parse(text) : undefined);
+}
+export function ok(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+export async function resolveCvId(user_id, cv_id) {
+    if (cv_id)
+        return cv_id;
+    const user = await cvpartnerFetch(`/v1/users/${user_id}`);
+    if (!user.default_cv_id) {
+        throw new Error(`User ${user_id} has no default_cv_id; pass cv_id explicitly`);
+    }
+    return user.default_cv_id;
+}

package/dist/index.js

@@ -1,139 +1,16 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-// Environment variables
-const API_KEY = process.env.CVPARTNER_API_KEY;
-const ORG = process.env.CVPARTNER_ORG || "snokam";
-const BASE_URL = `https://${ORG}.cvpartner.com/api`;
-async function cvpartnerFetch(endpoint, options = {}) {
-    if (!API_KEY) {
-        throw new Error("CVPARTNER_API_KEY environment variable is required");
-    }
-    const response = await fetch(`${BASE_URL}${endpoint}`, {
-        ...options,
-        headers: {
-            Authorization: `Token token=${API_KEY}`,
-            "Content-Type": "application/json",
-            ...options.headers,
-        },
-    });
-    if (!response.ok) {
-        const error = await response.text();
-        throw new Error(`CVPartner API error: ${response.status} - ${error || response.statusText}`);
-    }
-    return response.json();
-}
+import { registerUserTools } from "./tools/users.js";
+import { registerCvTools } from "./tools/cvs.js";
+import { registerMasterdataTools } from "./tools/masterdata.js";
 const server = new McpServer({
     name: "cvpartner-mcp",
     version: "1.0.0",
 });
-// Tool: List all users/consultants
-server.tool("list_users", "List all users/consultants in CVPartner", {
-    include_deactivated: z
-        .boolean()
-        .default(false)
-        .describe("Include deactivated users"),
-}, async ({ include_deactivated }) => {
-    const users = await cvpartnerFetch("/v1/users");
-    const filtered = include_deactivated
-        ? users
-        : users.filter((u) => !u.deactivated);
-    const simplified = filtered.map((u) => ({
-        user_id: u.user_id,
-        name: u.name,
-        email: u.email,
-        title: u.title?.no || u.title?.int || null,
-        telephone: u.telephone,
-        office: u.office_name,
-        cv_id: u.default_cv_id,
-    }));
-    return {
-        content: [{ type: "text", text: JSON.stringify(simplified, null, 2) }],
-    };
-});
-// Tool: Search CVs
-server.tool("search_cvs", "Search CVs by name, skills, or experience", {
-    query: z.string().describe("Search query (name, skill, technology, etc.)"),
-    size: z.number().default(10).describe("Maximum number of results"),
-}, async ({ query, size }) => {
-    const response = await cvpartnerFetch("/v4/search", {
-        method: "POST",
-        body: JSON.stringify({ query, size }),
-    });
-    const results = response.cvs.map((r) => ({
-        user_id: r.cv.user_id,
-        name: r.cv.name,
-        email: r.cv.email,
-        title: r.cv.title || r.cv.titles?.no || r.cv.titles?.int,
-        telephone: r.cv.telephone,
-        highlight: r.highlight,
-    }));
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ total: response.total, results }, null, 2),
-            },
-        ],
-    };
-});
-// Tool: Get user details
-server.tool("get_user", "Get detailed information about a specific user", {
-    user_id: z.string().describe("User ID from CVPartner"),
-}, async ({ user_id }) => {
-    const user = await cvpartnerFetch(`/v1/users/${user_id}`);
-    return {
-        content: [{ type: "text", text: JSON.stringify(user, null, 2) }],
-    };
-});
-// Tool: Get CV details
-server.tool("get_cv", "Get full CV content for a user", {
-    user_id: z.string().describe("User ID"),
-    cv_id: z.string().describe("CV ID (from user's default_cv_id)"),
-    language: z
-        .enum(["no", "int"])
-        .default("no")
-        .describe("Language version (no=Norwegian, int=English)"),
-}, async ({ user_id, cv_id, language: _language }) => {
-    const cv = await cvpartnerFetch(`/v1/cvs/${user_id}/${cv_id}`);
-    return {
-        content: [{ type: "text", text: JSON.stringify(cv, null, 2) }],
-    };
-});
-// Tool: Search by technology/skill
-server.tool("find_consultants_by_skill", "Find consultants with specific skills or technologies", {
-    skill: z
-        .string()
-        .describe("Skill or technology to search for (e.g., React, Python, Azure)"),
-    limit: z.number().default(10).describe("Maximum number of results"),
-}, async ({ skill, limit }) => {
-    const response = await cvpartnerFetch("/v4/search", {
-        method: "POST",
-        body: JSON.stringify({
-            query: skill,
-            size: limit,
-            filter_fields: ["technologies", "project_experiences"],
-        }),
-    });
-    const results = response.cvs
-        .filter((r) => !r.cv.is_deactivated)
-        .map((r) => ({
-        name: r.cv.name,
-        email: r.cv.email,
-        title: r.cv.title || r.cv.titles?.no,
-        match: r.highlight,
-    }));
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ skill, total: response.total, consultants: results }, null, 2),
-            },
-        ],
-    };
-});
-// Start server
+registerUserTools(server);
+registerCvTools(server);
+registerMasterdataTools(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/cvs.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCvTools(server: McpServer): void;

package/dist/tools/cvs.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { cvpartnerFetch, ok, resolveCvId, } from "../client.js";
+async function fetchCv(user_id, cv_id) {
+    const resolved = await resolveCvId(user_id, cv_id);
+    return cvpartnerFetch(`/v3/cvs/${user_id}/${resolved}`);
+}
+function extractSection(cv, candidates) {
+    for (const key of candidates) {
+        if (cv[key] !== undefined) {
+            return { section: key, data: cv[key] };
+        }
+    }
+    return { available_sections: Object.keys(cv) };
+}
+const SECTION_TOOLS = [
+    {
+        name: "get_key_qualifications",
+        description: "Get a consultant's key qualifications / summary",
+        keys: ["key_qualifications"],
+    },
+    {
+        name: "get_work_experience",
+        description: "Get a consultant's employment / work experience",
+        keys: ["work_experiences"],
+    },
+    {
+        name: "get_project_experience",
+        description: "Get a consultant's project/assignment experience",
+        keys: ["project_experiences"],
+    },
+    {
+        name: "get_education",
+        description: "Get a consultant's education history",
+        keys: ["educations"],
+    },
+    {
+        name: "get_certifications",
+        description: "Get a consultant's certifications",
+        keys: ["certifications"],
+    },
+    {
+        name: "get_courses",
+        description: "Get a consultant's courses",
+        keys: ["courses"],
+    },
+    {
+        name: "get_languages",
+        description: "Get the languages a consultant speaks",
+        keys: ["languages"],
+    },
+    {
+        name: "get_technologies",
+        description: "Get a consultant's technologies / skill categories",
+        keys: ["technologies", "technology_skills"],
+    },
+    {
+        name: "get_references",
+        description: "Get a consultant's references / recommendations",
+        keys: ["recommendations", "references"],
+    },
+    {
+        name: "get_presentations",
+        description: "Get a consultant's presentations / talks",
+        keys: ["presentations"],
+    },
+    {
+        name: "get_blogs",
+        description: "Get a consultant's blog posts / articles",
+        keys: ["blogs"],
+    },
+    {
+        name: "get_awards",
+        description: "Get a consultant's awards / honors",
+        keys: ["honors_awards", "awards", "honors"],
+    },
+];
+export function registerCvTools(server) {
+    server.tool("get_cv", "Get full CV content for a consultant", {
+        user_id: z.string().describe("User ID"),
+        cv_id: z
+            .string()
+            .optional()
+            .describe("CV ID; defaults to the user's default_cv_id when omitted"),
+    }, async ({ user_id, cv_id }) => {
+        const cv = await fetchCv(user_id, cv_id);
+        return ok(cv);
+    });
+    server.tool("list_cv_sections", "List the available section keys present in a consultant's CV", {
+        user_id: z.string().describe("User ID"),
+        cv_id: z.string().optional().describe("CV ID; defaults to default_cv_id"),
+    }, async ({ user_id, cv_id }) => {
+        const cv = await fetchCv(user_id, cv_id);
+        return ok({ available_sections: Object.keys(cv) });
+    });
+    server.tool("get_cv_section", "Get a single named section from a consultant's CV", {
+        user_id: z.string().describe("User ID"),
+        section: z
+            .string()
+            .describe("Section key, e.g. project_experiences, work_experiences, technologies, languages"),
+        cv_id: z.string().optional().describe("CV ID; defaults to default_cv_id"),
+    }, async ({ user_id, section, cv_id }) => {
+        const cv = await fetchCv(user_id, cv_id);
+        return ok(extractSection(cv, [section]));
+    });
+    for (const tool of SECTION_TOOLS) {
+        server.tool(tool.name, tool.description, {
+            user_id: z.string().describe("User ID"),
+            cv_id: z
+                .string()
+                .optional()
+                .describe("CV ID; defaults to default_cv_id"),
+        }, async ({ user_id, cv_id }) => {
+            const cv = await fetchCv(user_id, cv_id);
+            return ok(extractSection(cv, tool.keys));
+        });
+    }
+    server.tool("search_cvs", "Search CVs by name, skills, or experience (free text)", {
+        query: z
+            .string()
+            .describe("Search query (name, skill, technology, etc.)"),
+        size: z.number().default(10).describe("Maximum number of results"),
+        offset: z.number().default(0).describe("Pagination offset"),
+        office_ids: z
+            .array(z.string())
+            .optional()
+            .describe("Restrict to specific office IDs"),
+    }, async ({ query, size, offset, office_ids }) => {
+        const body = { query, size, offset };
+        if (office_ids)
+            body.office_ids = office_ids;
+        const response = await cvpartnerFetch("/v4/search", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        const results = response.cvs.map((r) => ({
+            user_id: r.cv.user_id,
+            cv_id: r.cv.id,
+            name: r.cv.name,
+            email: r.cv.email,
+            title: r.cv.title || r.cv.titles?.no || r.cv.titles?.int,
+            telephone: r.cv.telephone,
+            highlight: r.highlight,
+        }));
+        return ok({ total: response.total, results });
+    });
+    server.tool("find_consultants_by_skill", "Find consultants with specific skills or technologies", {
+        skill: z
+            .string()
+            .describe("Skill or technology to search for (e.g. React, Python, Azure)"),
+        limit: z.number().default(10).describe("Maximum number of results"),
+    }, async ({ skill, limit }) => {
+        const response = await cvpartnerFetch("/v4/search", {
+            method: "POST",
+            body: JSON.stringify({
+                query: skill,
+                size: limit,
+                filter_fields: ["technologies", "project_experiences"],
+            }),
+        });
+        const results = response.cvs
+            .filter((r) => !r.cv.is_deactivated)
+            .map((r) => ({
+            user_id: r.cv.user_id,
+            name: r.cv.name,
+            email: r.cv.email,
+            title: r.cv.title || r.cv.titles?.no,
+            match: r.highlight,
+        }));
+        return ok({ skill, total: response.total, consultants: results });
+    });
+}

package/dist/tools/masterdata.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMasterdataTools(server: McpServer): void;

package/dist/tools/masterdata.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { cvpartnerFetch, ok } from "../client.js";
+export function registerMasterdataTools(server) {
+    server.tool("list_countries", "List countries with their offices and departments", {}, async () => {
+        const countries = await cvpartnerFetch("/v1/masterdata/countries");
+        return ok(countries);
+    });
+    server.tool("list_offices", "List all offices flattened across countries", {}, async () => {
+        const countries = await cvpartnerFetch("/v1/masterdata/countries");
+        const offices = countries.flatMap((c) => (c.offices || []).map((o) => ({
+            office_id: o.id,
+            office_name: o.name,
+            country: c.name,
+            country_code: c.code,
+        })));
+        return ok(offices);
+    });
+    server.tool("list_departments", "List all departments flattened across offices", {}, async () => {
+        const countries = await cvpartnerFetch("/v1/masterdata/countries");
+        const departments = countries.flatMap((c) => (c.offices || []).flatMap((o) => (o.departments || []).map((d) => ({
+            department_id: d.id,
+            department_name: d.name,
+            office_id: o.id,
+            office_name: o.name,
+            country: c.name,
+        }))));
+        return ok(departments);
+    });
+    server.tool("list_custom_tag_categories", "List custom tag categories and their tags (masterdata)", {}, async () => {
+        const categories = await cvpartnerFetch("/v1/masterdata/custom_tags/custom_tag_category");
+        return ok(categories);
+    });
+    server.tool("search_customers", "Search customers/clients by name", {
+        name: z.string().describe("Full or partial customer name"),
+    }, async ({ name }) => {
+        const results = await cvpartnerFetch(`/v2/customers/search?name=${encodeURIComponent(name)}`);
+        return ok(results);
+    });
+}

package/dist/tools/users.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerUserTools(server: McpServer): void;

package/dist/tools/users.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { cvpartnerFetch, ok } from "../client.js";
+export function registerUserTools(server) {
+    server.tool("list_users", "List all users/consultants in CVPartner", {
+        include_deactivated: z
+            .boolean()
+            .default(false)
+            .describe("Include deactivated users"),
+    }, async ({ include_deactivated }) => {
+        const users = await cvpartnerFetch("/v1/users");
+        const filtered = include_deactivated
+            ? users
+            : users.filter((u) => !u.deactivated);
+        const simplified = filtered.map((u) => ({
+            user_id: u.user_id,
+            name: u.name,
+            email: u.email,
+            title: u.title?.no || u.title?.int || null,
+            telephone: u.telephone,
+            office: u.office_name,
+            cv_id: u.default_cv_id,
+        }));
+        return ok(simplified);
+    });
+    server.tool("get_user", "Get detailed information about a specific user/consultant", {
+        user_id: z.string().describe("User ID from CVPartner"),
+    }, async ({ user_id }) => {
+        const user = await cvpartnerFetch(`/v1/users/${user_id}`);
+        return ok(user);
+    });
+    server.tool("list_users_created_after", "List users created after a given date (incremental sync)", {
+        created_after: z
+            .string()
+            .describe("Date in DD-MM-YYYY format, e.g. 27-09-2021"),
+        offset: z.number().default(0).describe("Pagination offset"),
+    }, async ({ created_after, offset }) => {
+        const users = await cvpartnerFetch(`/v1/users?offset=${offset}&created_after=${encodeURIComponent(created_after)}`);
+        return ok(users);
+    });
+    server.tool("search_users", "Search users by name (quick lookup)", {
+        name: z.string().describe("Full or partial name to search for"),
+    }, async ({ name }) => {
+        const results = await cvpartnerFetch(`/v2/users/search?name=${encodeURIComponent(name)}`);
+        return ok(results);
+    });
+    server.tool("search_users_advanced", "Advanced user search across free text, name and technology skills", {
+        query: z.string().describe("Free-text query (name, skill, keyword)"),
+        size: z.number().default(20).describe("Maximum number of results"),
+        offset: z.number().default(0).describe("Pagination offset"),
+    }, async ({ query, size, offset }) => {
+        const results = await cvpartnerFetch("/v4/users/search", {
+            method: "POST",
+            body: JSON.stringify({ query, size, offset }),
+        });
+        return ok(results);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snokam/mcp-cvpartner",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "MCP server for CVPartner CV management with Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -14,11 +14,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "tsx": "^4.21.0",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.2"
   },
   "files": [