@codegame.dev/careerflow-mcp 1.1.0

package/dist/helpers.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { ApiError } from "./client.js";
+/**
+ * Shared shapes and formatting used across tool modules.
+ */
+export const companyIdSchema = z
+    .number()
+    .int()
+    .optional()
+    .describe("Company id. Optional when the server is configured with CAREERFLOW_COMPANY_ID; " +
+    "required otherwise, or to act in a different company.");
+/**
+ * Resolves the company for a call. Kept in one place so every tool behaves the
+ * same way when the id is omitted, and so the error names the fix.
+ */
+export function resolveCompanyId(client, provided) {
+    const companyId = provided ?? client.defaultCompanyId;
+    if (companyId === undefined) {
+        throw new Error("No company id given and CAREERFLOW_COMPANY_ID is not set. " +
+            "Pass company_id, or set CAREERFLOW_COMPANY_ID on the server.");
+    }
+    return companyId;
+}
+export function textResult(value) {
+    const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+export function errorResult(error) {
+    const message = error instanceof ApiError ? error.message : error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+/**
+ * Wraps a tool handler so a thrown error becomes a readable tool result rather
+ * than a transport-level failure the model cannot interpret or recover from.
+ */
+export function safeHandler(handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    };
+}
+/**
+ * Trims a task down to the fields an assistant actually reasons about. The raw
+ * rows carry ~40 columns of bookkeeping (activity flags, snapshot ids, ordering
+ * numbers) that would otherwise crowd out the useful content of a result.
+ */
+export function summariseTask(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        description: task.description || undefined,
+        project_id: task.project_id,
+        project_title: task.project_title || task.project_name || undefined,
+        board_id: task.board_id,
+        board_name: task.board_name || undefined,
+        is_completed: Boolean(task.is_completed),
+        priority: task.priority,
+        start_date: task.start_date || undefined,
+        due_date: task.due_date || undefined,
+        completion_date: task.completion_date || undefined,
+        time_estimate_minutes: task.time_estimate_minutes ?? undefined,
+        time_minutes: task.time_minutes ?? undefined,
+        review_status: task.review_status || undefined,
+        review_score: task.review_score ?? undefined,
+        is_archived: Boolean(task.is_archived),
+        members: Array.isArray(task.members)
+            ? task.members.map((m) => ({
+                user_id: m.user_id ?? m.id,
+                name: [m.firstname, m.lastname].filter(Boolean).join(" ") || m.staff_number_with_prefix
+            }))
+            : undefined,
+        labels: Array.isArray(task.labels)
+            ? task.labels.map((l) => ({ id: l.id, title: l.title }))
+            : undefined
+    };
+}
+export function summariseUser(user) {
+    return {
+        id: user.id,
+        name: [user.firstname, user.lastname].filter(Boolean).join(" ") || undefined,
+        staff_number: user.staff_number_with_prefix || user.staff_number || undefined,
+        email: user.email || undefined,
+        mobile: user.mobile || undefined,
+        type: user.type,
+        company_id: user.company_id ?? undefined,
+        position: user.position || user.job_title || undefined
+    };
+}
+/**
+ * Fetches a single task by id alone.
+ *
+ * `kanbans/tasks/get` needs project_id and board_id alongside the task id, which
+ * a caller working from a task number will not have. Task search accepts a bare
+ * id and returns the same row plus its project/board, so it is used as the
+ * lookup and the ids come back with the task.
+ *
+ * The read matters for more than convenience: `kanbans/tasks/edit` replaces the
+ * whole row, so any field omitted falls back to a default (is_completed -> false,
+ * priority -> "medium"). Every edit reads the task first and merges onto it — see
+ * `mergeTaskEdit` — so a partial change cannot silently clear untouched fields.
+ */
+export async function fetchTask(client, companyId, taskId) {
+    const response = await client.get("kanbans/tasks/search", {
+        company_id: companyId,
+        task_id: taskId,
+        limit: 1
+    });
+    const { items: tasks } = extractList(response.data, "tasks");
+    const task = tasks.find((t) => Number(t.id) === Number(taskId)) ?? tasks[0];
+    if (!task || task.id === undefined) {
+        throw new Error(`Task ${taskId} was not found, or is not visible to this token.`);
+    }
+    return task;
+}
+/**
+ * Builds the full body for `kanbans/tasks/edit` by layering the requested
+ * changes over the task's current values, so unmentioned fields survive.
+ */
+export function mergeTaskEdit(current, companyId, changes) {
+    const labelIds = Array.isArray(current.labels)
+        ? current.labels.map((l) => l.id).join(",")
+        : undefined;
+    const base = {
+        company_id: companyId,
+        project_id: current.project_id,
+        board_id: current.board_id,
+        task_id: current.id,
+        title: current.title,
+        description: current.description ?? "",
+        is_completed: Boolean(current.is_completed),
+        start_date: current.start_date ?? null,
+        due_date: current.due_date ?? null,
+        priority: current.priority ?? "medium",
+        time_estimate_minutes: current.time_estimate_minutes ?? null,
+        label_ids: labelIds
+    };
+    for (const [key, value] of Object.entries(changes)) {
+        if (value !== undefined) {
+            base[key] = value;
+        }
+    }
+    return base;
+}
+/**
+ * The authenticated user's id, cached for the process lifetime.
+ *
+ * Several endpoints scope a read to one user and reject an unscoped
+ * company-wide query unless the caller holds an admin role, so tools pass this
+ * to mean "mine". The token maps to a fixed user, so the lookup is done once.
+ */
+let cachedUserId;
+export async function currentUserId(client) {
+    if (cachedUserId !== undefined) {
+        return cachedUserId;
+    }
+    const response = await client.get("users/profile", {});
+    const id = response.data?.id;
+    if (id !== undefined) {
+        cachedUserId = Number(id);
+    }
+    return cachedUserId;
+}
+/**
+ * Pulls a list and its total out of a response payload.
+ *
+ * The API nests both inside `data` — the rows under an endpoint-specific key and
+ * the count under `total` — rather than putting a count on the envelope, so the
+ * key is named per call site and the total read from beside it.
+ */
+export function extractList(data, key) {
+    if (Array.isArray(data)) {
+        return { items: data };
+    }
+    if (data && typeof data === "object") {
+        const record = data;
+        const items = Array.isArray(record[key]) ? record[key] : [];
+        const total = typeof record.total === "number" ? record.total : undefined;
+        return { items, total };
+    }
+    return { items: [] };
+}
+/** The API takes booleans as 1/0 in form fields. */
+export function boolParam(value) {
+    if (value === undefined)
+        return undefined;
+    return value ? 1 : 0;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { CareerFlowClient } from "./client.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerWorkspaceTools } from "./tools/workspace.js";
+import { registerTimeTools } from "./tools/time.js";
+import { registerChatTools } from "./tools/chat.js";
+import { registerChatExtraTools } from "./tools/chat-extra.js";
+import { registerWorkplaceTools } from "./tools/workplace.js";
+import { registerKanbanExtraTools } from "./tools/kanban-extra.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerAdminTools } from "./tools/admin.js";
+import { registerCrmTools } from "./tools/crm.js";
+import { registerCrmAdminTools } from "./tools/crm-admin.js";
+import { registerHrTools } from "./tools/hr.js";
+import { registerBenefitFundTools } from "./tools/benefit-funds.js";
+import { registerFormTools } from "./tools/forms.js";
+import { registerCmsTools } from "./tools/cms.js";
+import { registerDevTicketTools } from "./tools/dev-tickets.js";
+import { registerMiscTools } from "./tools/misc.js";
+const require = createRequire(import.meta.url);
+let version = "unknown";
+try {
+    version = require("../package.json").version;
+}
+catch {
+    // package.json sits outside dist/; missing it only affects the reported version
+}
+/**
+ * Tool groups, in registration order. Each entry may hold several modules that
+ * belong to one user-facing group — e.g. `crm` spans contacts/deals/activities
+ * and CRM configuration.
+ *
+ * CAREERFLOW_GROUPS (allowlist) and CAREERFLOW_EXCLUDE_GROUPS (denylist) take
+ * comma-separated names from here. Useful in clients that load every tool's
+ * schema into the model's context: a token scoped to one domain can register
+ * only that domain's tools.
+ */
+const toolGroups = [
+    { name: "workspace", description: "whoami, companies, users", register: registerWorkspaceTools },
+    { name: "tasks", description: "tasks and comments", register: registerTaskTools },
+    { name: "kanban", description: "boards, labels, checklists, attachments", register: registerKanbanExtraTools },
+    { name: "projects", description: "projects and membership", register: registerProjectTools },
+    { name: "time", description: "timers and time entries", register: registerTimeTools },
+    {
+        name: "chat",
+        description: "chats, groups, messages",
+        register: (server, client) => {
+            registerChatTools(server, client);
+            registerChatExtraTools(server, client);
+        }
+    },
+    { name: "workplace", description: "announcements, surveys, attendance", register: registerWorkplaceTools },
+    { name: "admin", description: "company and user administration", register: registerAdminTools },
+    {
+        name: "crm",
+        description: "contacts, deals, activities, pipelines",
+        register: (server, client) => {
+            registerCrmTools(server, client);
+            registerCrmAdminTools(server, client);
+        }
+    },
+    { name: "hr", description: "payroll, reviews, notes, careers, onboarding, cafeteria", register: registerHrTools },
+    { name: "benefit-funds", description: "loans, lotteries, membership", register: registerBenefitFundTools },
+    { name: "forms", description: "forms and submissions", register: registerFormTools },
+    { name: "cms", description: "posts and custom pages", register: registerCmsTools },
+    { name: "dev-tickets", description: "support tickets", register: registerDevTicketTools },
+    { name: "misc", description: "addresses, surveys, announcements, billing", register: registerMiscTools }
+];
+const USAGE = `CareerFlow MCP server — connects an AI assistant to CareerFlow.
+
+Usage:
+  npx @codegame.dev/careerflow-mcp            Start the MCP server over stdio (what a client runs)
+  npx @codegame.dev/careerflow-mcp init       Guided setup: asks for your token, then wires up your client
+  npx @codegame.dev/careerflow-mcp --help     Show this help
+  npx @codegame.dev/careerflow-mcp --version  Show the version
+
+init options (all optional; safe to share — the token is always prompted for
+separately, hidden, and never read from the command line):
+  --base-url <url>     CareerFlow host, e.g. https://app.example.com
+  --name <name>        Server name in the client config (default: careerflow)
+  --company-id <id>    Default company, so tools need no company_id
+  --client <id>        claude-code, claude-desktop, zcode, cursor, or other
+
+Example one-liner for onboarding pages:
+  npx @codegame.dev/careerflow-mcp init --base-url https://app.example.com --name acme --client claude-code
+
+Environment:
+  CAREERFLOW_TOKEN            Required. Personal access token (Settings > Access Tokens)
+  CAREERFLOW_BASE_URL         Required. Your CareerFlow API root
+  CAREERFLOW_COMPANY_ID       Optional. Default company, so tools need no company_id
+  CAREERFLOW_TIMEOUT_MS       Optional. Request timeout, default 30000
+  CAREERFLOW_GROUPS           Optional. Comma-separated tool groups to register
+                              (${toolGroups.map((g) => g.name).join(", ")})
+  CAREERFLOW_EXCLUDE_GROUPS   Optional. Comma-separated groups to leave out
+
+Docs: https://www.npmjs.com/package/@codegame.dev/careerflow-mcp`;
+/** Parses CAREERFLOW_GROUPS / CAREERFLOW_EXCLUDE_GROUPS into a group allowlist, or dies naming the valid groups. */
+function selectGroups(env) {
+    const parse = (raw) => (raw ?? "")
+        .split(",")
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean);
+    const include = parse(env.CAREERFLOW_GROUPS);
+    const exclude = parse(env.CAREERFLOW_EXCLUDE_GROUPS);
+    const valid = new Set(toolGroups.map((g) => g.name));
+    const unknown = [...include, ...exclude].filter((name) => !valid.has(name));
+    if (unknown.length) {
+        throw new Error(`Unknown tool group(s): ${unknown.join(", ")}. Valid groups: ${[...valid].join(", ")}.`);
+    }
+    let selected = toolGroups;
+    if (include.length) {
+        const allow = new Set(include);
+        selected = selected.filter((g) => allow.has(g.name));
+        if (!selected.length) {
+            throw new Error("CAREERFLOW_GROUPS left no tool groups to register.");
+        }
+    }
+    if (exclude.length) {
+        const deny = new Set(exclude);
+        selected = selected.filter((g) => !deny.has(g.name));
+        if (!selected.length) {
+            throw new Error("CAREERFLOW_EXCLUDE_GROUPS left no tool groups to register.");
+        }
+    }
+    return selected;
+}
+async function serve() {
+    const config = loadConfig();
+    const client = new CareerFlowClient(config);
+    const groups = selectGroups(process.env);
+    const server = new McpServer({
+        name: "careerflow",
+        version
+    }, {
+        instructions: "Tools for CareerFlow, a workplace platform: tasks and kanban boards, projects, time " +
+            "tracking, chat, CRM (contacts/deals/activities), HR (payroll, disciplinary and " +
+            "administrative notes, careers, onboarding), the benefit fund (loans and lotteries), " +
+            "forms, CMS, and company/user administration.\n\n" +
+            "Guidance:\n" +
+            "- Call whoami first when a request depends on who 'I' or 'me' is, or before any tool " +
+            "that takes company_id — whoami's response already includes every company the user " +
+            "belongs to (and resolves company_id outright if there's only one), so don't call a " +
+            "company-scoped tool without a company_id and wait for it to fail first.\n" +
+            "- Task writes need project and board ids: resolve them with list_projects and list_boards.\n" +
+            "- CRM writes need pipeline and stage ids: resolve them with crm_list_pipelines and crm_list_stages.\n" +
+            "- Resolve people to user ids with find_user or list_project_members before assigning work.\n" +
+            "- Some tools have a real, hard-to-undo effect and say so in their own description — " +
+            "send_message, create_administrative_note, and message_form_submission deliver to real " +
+            "people; create_user, set_user_status, and set_user_role change real accounts; " +
+            "request_benefit_fund_loan, update_benefit_fund_loan_status, " +
+            "pay_benefit_fund_loan_installment, and respond_to_lottery_win touch real money. Confirm " +
+            "details with the user before calling any of these.\n" +
+            "- A 403 means the token lacks a scope; tell the user which scope to add in " +
+            "Settings > Access Tokens rather than retrying."
+    });
+    for (const group of groups) {
+        group.register(server, client);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout carries the MCP protocol stream, so anything human-facing must go to
+    // stderr or it corrupts the transport
+    console.error(`careerflow-mcp connected (api: ${config.baseUrl}, groups: ${groups.map((g) => g.name).join(", ")})`);
+}
+const [, , command] = process.argv;
+if (command === "--help" || command === "-h") {
+    console.log(USAGE);
+}
+else if (command === "--version" || command === "-v") {
+    console.log(version);
+}
+else if (command === "init") {
+    import("./setup.js")
+        .then(({ runSetup }) => runSetup(process.argv.slice(3)))
+        .catch((error) => {
+        console.error(`careerflow-mcp init failed: ${error.message}`);
+        process.exit(1);
+    });
+}
+else if (command === undefined) {
+    serve().catch((error) => {
+        console.error(`careerflow-mcp failed to start: ${error.message}`);
+        process.exit(1);
+    });
+}
+else {
+    console.error(`Unknown command: ${command}\n\n${USAGE}`);
+    process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}