mcp-costlocker 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+## MCP Configuration
+
+This project provides a Model Context Protocol (MCP) server that exposes two tools:
+
+- `costlocker_get_time_entries`
+- `costlocker_update_time_entries`
+
+These tools interact with your Costlocker GraphQL API. You need to provide the `COSTLOCKER_API_KEY` in the environment.
+
+### From npm (no local clone)
+
+After the package is published to npm as `mcp-costlocker` (unscoped, public by default), use `npx` so Node downloads the package on first run. You do not need `pnpm` or a checkout of this repository.
+
+```json
+{
+  "mcpServers": {
+    "costlocker": {
+      "command": "npx",
+      "args": ["-y", "mcp-costlocker"],
+      "env": {
+        "COSTLOCKER_API_KEY": "YOUR_STATIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Optional: pin a version with `mcp-costlocker@0.1.0` instead of trusting `latest` resolution via `npx`.
+
+The name `costlocker-mcp` is already taken on npm; this package publishes as `mcp-costlocker`. Before the first publish, confirm the name is still free: `npm view mcp-costlocker`.
+
+### From a local clone (npm, yarn, or pnpm)
+
+Install dependencies once in the repo, then point MCP at `npm` (or your preferred package manager) and the `start` script. Example for npm:
+
+```json
+{
+  "mcpServers": {
+    "costlocker": {
+      "command": "npm",
+      "args": ["start"],
+      "cwd": "/absolute/path/to/costlocker-mcp",
+      "env": {
+        "COSTLOCKER_API_KEY": "YOUR_STATIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- Replace `cwd` with the absolute path to this repository.
+- `pnpm start` or `yarn start` work the same way if you prefer those tools.
+
+Development builds TypeScript on the fly (`tsx src/index.ts`). For a run that uses the compiled server only, run `npm run build` and start with `node dist/index.js` (or rely on the published package, which already uses `dist/`).
+
+### Integrating with Cursor
+
+Use one of the JSON snippets above in Cursor MCP settings (`npx` for published package, or `npm` + `cwd` for a local clone).
+
+### Integrating with Antigravity
+
+Antigravity can connect natively to MCP servers via its configuration file.
+
+1. Locate your Antigravity MCP settings.
+2. Add the same `costlocker` server entry as in the Cursor examples (`npx` or local `npm` + `cwd`).
+
+### Publishing (maintainers)
+
+- `npm run build` produces `dist/` (also run automatically via `prepublishOnly` before `npm publish`).
+- Unscoped packages are public on npm; you only need a logged-in account (`npm login`) and an unused package name. Publish with `npm publish` (no `--access public` required unless you use a scoped name).

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getCostlockerEntriesList, getCostlockerEntriesListForPerson, } from "./integrations/costlocker/queries/getCostlockerEntries.js";
+import { updateCostlockerEntryDescriptions, } from "./integrations/costlocker/mutations/updateCostlockerEntry.js";
+import { sdk } from "./integrations/costlocker/client.js";
+import { registerCostlockerGraphTools } from "./tools/registerCostlockerGraphTools.js";
+// --- Env validation ---
+const COSTLOCKER_API_KEY = process.env.COSTLOCKER_API_KEY;
+if (!COSTLOCKER_API_KEY) {
+    process.stderr.write("Missing COSTLOCKER_API_KEY environment variable.\n");
+    process.exit(1);
+}
+// --- Server setup ---
+const server = new McpServer({ name: "mcp-costlocker", version: "1.0.0" });
+server.registerTool("costlocker_get_time_entries", {
+    description: "Get Costlocker time entries for a given date. Optionally filter by person ID.",
+    inputSchema: {
+        target_date: z.string().describe("Date in YYYY-MM-DD format"),
+        person_id: z.number().optional().describe("Optional person ID to filter by. If omitted, returns entries for all people."),
+    },
+}, async ({ target_date, person_id }) => {
+    try {
+        const hasPersonId = typeof person_id !== "undefined";
+        const entries = hasPersonId
+            ? await getCostlockerEntriesListForPerson({
+                target_date,
+                person_id,
+            })
+            : await getCostlockerEntriesList({ target_date });
+        return {
+            content: [{ type: "text", text: JSON.stringify(entries, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool("costlocker_update_time_entries", {
+    description: "Update descriptions of Costlocker time entries given their UUIDs.",
+    inputSchema: {
+        updates: z.array(z.object({
+            uuid: z.string(),
+            description: z.string(),
+        })).min(1).describe("List of entries to update containing the UUID and the new description."),
+    },
+}, async ({ updates }) => {
+    try {
+        const results = await updateCostlockerEntryDescriptions({ updates });
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+registerCostlockerGraphTools(server, sdk);
+// --- Error handling ---
+process.on("uncaughtException", (error) => {
+    process.stderr.write(`Uncaught Exception: ${error}\n`);
+    process.exit(1);
+});
+process.on("unhandledRejection", (error) => {
+    process.stderr.write(`Unhandled Rejection: ${error}\n`);
+    process.exit(1);
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("Costlocker MCP server started dynamically\n");
+}
+main().catch((error) => {
+    process.stderr.write(`Startup Error: ${error}\n`);
+    process.exit(1);
+});

package/dist/integrations/costlocker/client.js

@@ -0,0 +1,58 @@
+import process from "node:process";
+import { getSdk } from "./generated/client.js";
+export function validateDate(date) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new Error(`Invalid date "${date}". Expected YYYY-MM-DD format.`);
+    }
+    return date;
+}
+export function toNextDate(date) {
+    const dateObj = new Date(`${date}T00:00:00.000Z`);
+    if (Number.isNaN(dateObj.getTime())) {
+        throw new Error(`Invalid date "${date}"`);
+    }
+    dateObj.setUTCDate(dateObj.getUTCDate() + 1);
+    return dateObj.toISOString().slice(0, 10);
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing ${name} in environment.`);
+    }
+    return value;
+}
+function getEndpoint() {
+    return process.env.COSTLOCKER_GRAPHQL_URL ?? "https://api.costlocker.com/graphql";
+}
+function getHeaders() {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Static ${requireEnv("COSTLOCKER_API_KEY")}`,
+    };
+}
+async function postGraphQl(query, variables) {
+    const response = await fetch(getEndpoint(), {
+        method: "POST",
+        headers: getHeaders(),
+        body: JSON.stringify({
+            query,
+            variables,
+        }),
+    });
+    if (!response.ok) {
+        const bodyText = typeof response.text === "function" ? await response.text() : "";
+        throw new Error(`Costlocker request failed with ${response.status} ${response.statusText}${bodyText ? "\\n" + bodyText : ""}`);
+    }
+    const payload = (await response.json());
+    if (payload.errors?.length) {
+        throw new Error(`GraphQL error: ${payload.errors.map((error) => error.message).join("; ")}`);
+    }
+    return payload;
+}
+const requester = async (doc, vars) => {
+    const queryString = typeof doc === "string" ? doc : doc?.loc?.source?.body ?? String(doc);
+    const payload = await postGraphQl(queryString, vars || {});
+    return payload.data;
+};
+export const sdk = getSdk(requester);