@timesheetai/mcp 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ktria Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @timesheetai/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+**TimesheetAI**. It lets AI agents (Codex, Claude Code, Claude Desktop, Cursor,
+…) read your projects and log time on your behalf.
+
+Motivating workflow: at the end of the day, ask your agent to summarize what it
+worked on and have it call `add_time_entry` to record the time directly.
+
+## Tools
+
+| Tool             | What it does                                                              |
+| ---------------- | ------------------------------------------------------------------------- |
+| `list_workspaces`| List the workspaces your API key can access.                              |
+| `list_projects`  | List active projects and their active tasks (gives you `projectId`/`taskId`). |
+| `list_today`     | List your time entries for a day (defaults to today).                     |
+| `add_time_entry` | Log one entry: `projectId`, optional `taskId`, `date`, `start`, `end`, `description`. |
+
+Times are **wall-clock** (`HH:mm`), dates are `YYYY-MM-DD`. "Today" defaults to
+this machine's local date.
+
+`add_time_entry` is **idempotent** on an optional `clientRefId` (UUID). The
+client generates one per call automatically; to make a retry of the *same*
+logical add safe, pass the same `clientRefId` again — the backend returns the
+existing entry instead of creating a duplicate.
+
+## Configuration
+
+The server needs two settings:
+
+| Setting              | Env var                 | Default                          |
+| -------------------- | ----------------------- | -------------------------------- |
+| API key              | `TIMESHEETAI_API_KEY`   | _(required)_                     |
+| Backend base URL     | `TIMESHEETAI_BASE_URL`  | `https://alpha.timesheetai.app`  |
+
+Create an API key from your TimesheetAI account (Account Portal → API keys).
+
+Set them via your MCP host's `env` block (recommended), or in
+`~/.config/timesheetai/config.json`:
+
+```json
+{
+  "apiKey": "ak_...",
+  "baseUrl": "https://alpha.timesheetai.app"
+}
+```
+
+Environment variables take precedence over the config file.
+
+## Host setup
+
+> **Alpha release:** the package is published under the `alpha` npm dist-tag while it
+> targets the alpha backend, so install it as **`@timesheetai/mcp@alpha`** (a plain
+> `@timesheetai/mcp` has no `latest` yet). The alpha endpoint is the built-in default,
+> so `TIMESHEETAI_BASE_URL` is optional below.
+
+### Claude Desktop
+
+`claude_desktop_config.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "timesheetai": {
+      "command": "npx",
+      "args": ["-y", "@timesheetai/mcp@alpha"],
+      "env": {
+        "TIMESHEETAI_API_KEY": "ak_...",
+        "TIMESHEETAI_BASE_URL": "https://alpha.timesheetai.app"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add timesheetai \
+  --env TIMESHEETAI_API_KEY=ak_... \
+  --env TIMESHEETAI_BASE_URL=https://alpha.timesheetai.app \
+  -- npx -y @timesheetai/mcp@alpha
+```
+
+### Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.timesheetai]
+command = "npx"
+args = ["-y", "@timesheetai/mcp@alpha"]
+env = { TIMESHEETAI_API_KEY = "ak_...", TIMESHEETAI_BASE_URL = "https://alpha.timesheetai.app" }
+```
+
+## Local development
+
+Build, then run the compiled entrypoint directly:
+
+```bash
+pnpm --filter @timesheetai/mcp build
+TIMESHEETAI_API_KEY=ak_... TIMESHEETAI_BASE_URL=http://localhost:5173 \
+  node packages/mcp/dist/index.js
+```
+
+Before the package is published to npm, wire it into Claude Code by pointing at
+the **built `dist/` path** instead of `npx @timesheetai/mcp` (rebuild after any
+source change). Create the API key from the dev Account Portal → API keys; a
+key from your dev Clerk instance authenticates against the dev backend
+(`http://localhost:5173`):
+
+```bash
+claude mcp add timesheetai \
+  --env TIMESHEETAI_API_KEY=ak_... \
+  --env TIMESHEETAI_BASE_URL=http://localhost:5173 \
+  -- node /absolute/path/to/timesheet-app/packages/mcp/dist/index.js
+```
+
+Inspect interactively with the MCP Inspector:
+
+```bash
+TIMESHEETAI_API_KEY=ak_... TIMESHEETAI_BASE_URL=http://localhost:5173 \
+  npx @modelcontextprotocol/inspector node packages/mcp/dist/index.js
+```

package/dist/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared core: HTTP client over the TimesheetAI agent API. Thin wrapper that
+ * attaches the API key, builds query strings, and turns the backend's
+ * { error: { code, message } } envelope into a typed ApiError.
+ */
+import type { Config } from "./config.js";
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+export type Workspace = {
+    id: string;
+    name: string;
+    slug: string | null;
+    role: string;
+};
+export type Task = {
+    id: number;
+    name: string;
+    defaultBillable: boolean;
+};
+export type Project = {
+    id: number;
+    name: string;
+    defaultBillable: boolean;
+    tasks: Task[];
+};
+export type TimeEntry = {
+    id: number;
+    clientRefId: string;
+    date: string;
+    start: string;
+    end: string;
+    startTime: string;
+    endTime: string;
+    projectId: number | null;
+    taskId: number | null;
+    project: string | null;
+    task: string | null;
+    isBillable: boolean;
+    description: string;
+};
+export type AddTimeEntryInput = {
+    projectId: number;
+    taskId?: number;
+    date: string;
+    start: string;
+    end: string;
+    description?: string;
+    isBillable?: boolean;
+    workspace?: string;
+    /** Reused across retries for idempotency; generated if omitted. */
+    clientRefId?: string;
+};
+export declare class TimesheetClient {
+    private readonly config;
+    constructor(config: Config);
+    private request;
+    listWorkspaces(): Promise<{
+        workspaces: Workspace[];
+    }>;
+    listProjects(workspace?: string): Promise<{
+        workspace: {
+            id: string;
+            name: string;
+        };
+        projects: Project[];
+    }>;
+    listEntries(date: string, workspace?: string): Promise<{
+        workspace: {
+            id: string;
+            name: string;
+        };
+        date: string;
+        entries: TimeEntry[];
+    }>;
+    addTimeEntry(input: AddTimeEntryInput): Promise<{
+        workspace: {
+            id: string;
+            name: string;
+        };
+        entry: TimeEntry;
+        idempotent: boolean;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,75 @@
+/**
+ * Shared core: HTTP client over the TimesheetAI agent API. Thin wrapper that
+ * attaches the API key, builds query strings, and turns the backend's
+ * { error: { code, message } } envelope into a typed ApiError.
+ */
+import { randomUUID } from "node:crypto";
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "ApiError";
+    }
+}
+function queryString(params) {
+    const usable = Object.entries(params).filter(([, v]) => v !== undefined && v !== "");
+    if (usable.length === 0)
+        return "";
+    const sp = new URLSearchParams();
+    for (const [k, v] of usable)
+        sp.set(k, v);
+    return `?${sp.toString()}`;
+}
+export class TimesheetClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(path, init) {
+        let res;
+        try {
+            res = await fetch(`${this.config.baseUrl}${path}`, {
+                ...init,
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                    ...init?.headers,
+                },
+            });
+        }
+        catch (cause) {
+            throw new ApiError(0, "network_error", `Could not reach TimesheetAI at ${this.config.baseUrl}: ${cause?.message ?? cause}`);
+        }
+        const json = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const err = json?.error;
+            throw new ApiError(res.status, err?.code ?? "error", err?.message ?? `Request failed with HTTP ${res.status}`, err);
+        }
+        return json;
+    }
+    listWorkspaces() {
+        return this.request("/api/mcp/v1/workspaces");
+    }
+    listProjects(workspace) {
+        return this.request(`/api/mcp/v1/projects${queryString({ workspace })}`);
+    }
+    listEntries(date, workspace) {
+        return this.request(`/api/mcp/v1/entries${queryString({ date, workspace })}`);
+    }
+    addTimeEntry(input) {
+        // Stable idempotency key per logical add: reuse a caller-supplied id, else
+        // generate one here (before the request) so a transport-level retry of THIS
+        // body hits the backend's idempotency path instead of duplicating.
+        const body = { ...input, clientRefId: input.clientRefId ?? randomUUID() };
+        return this.request("/api/mcp/v1/time-entries", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared core: config + credential loading. Consumed by the MCP server now and
+ * the deferred CLI later. Credentials live outside any repo — env vars (set in
+ * the host's MCP config) or ~/.config/timesheetai/config.json.
+ */
+export type Config = {
+    apiKey: string;
+    baseUrl: string;
+};
+/** Alpha is the v1 target; override with TIMESHEETAI_BASE_URL for production. */
+export declare const DEFAULT_BASE_URL = "https://alpha.timesheetai.app";
+/**
+ * The canonical production host. Any other base URL is a non-production
+ * endpoint and is flagged in the startup banner so a tester is never silently
+ * pinned to alpha/local when they think they are on production (and vice versa).
+ */
+export declare const PRODUCTION_HOST = "timesheetai.app";
+/** Classify a base URL for the startup banner. */
+export declare function describeEndpoint(baseUrl: string): {
+    production: boolean;
+    label: string;
+};
+/**
+ * Resolve config. Precedence: environment variables > config file > defaults.
+ * Throws a clear error if no API key can be found.
+ */
+export declare function loadConfig(): Config;
+/**
+ * The user's local calendar day as YYYY-MM-DD. Intentionally uses local Date
+ * methods: the MCP server runs on the user's machine, so its local day IS the
+ * user's day. The backend then applies wall-clock/floating-time rules to this
+ * explicit date and never guesses a timezone (story Open Design Decision #4).
+ */
+export declare function localToday(): string;

package/dist/config.js

@@ -0,0 +1,82 @@
+/**
+ * Shared core: config + credential loading. Consumed by the MCP server now and
+ * the deferred CLI later. Credentials live outside any repo — env vars (set in
+ * the host's MCP config) or ~/.config/timesheetai/config.json.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Alpha is the v1 target; override with TIMESHEETAI_BASE_URL for production. */
+export const DEFAULT_BASE_URL = "https://alpha.timesheetai.app";
+/**
+ * The canonical production host. Any other base URL is a non-production
+ * endpoint and is flagged in the startup banner so a tester is never silently
+ * pinned to alpha/local when they think they are on production (and vice versa).
+ */
+export const PRODUCTION_HOST = "timesheetai.app";
+/** Classify a base URL for the startup banner. */
+export function describeEndpoint(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).host.toLowerCase();
+    }
+    catch {
+        return { production: false, label: "invalid URL" };
+    }
+    if (host === PRODUCTION_HOST || host === `www.${PRODUCTION_HOST}`) {
+        return { production: true, label: "production" };
+    }
+    if (host === `alpha.${PRODUCTION_HOST}`) {
+        return { production: false, label: "ALPHA test endpoint" };
+    }
+    if (host === "localhost" || host.startsWith("localhost:") || host.startsWith("127.0.0.1")) {
+        return { production: false, label: "local dev endpoint" };
+    }
+    return { production: false, label: "non-production endpoint" };
+}
+function configFilePath() {
+    return (process.env.TIMESHEETAI_CONFIG ??
+        join(homedir(), ".config", "timesheetai", "config.json"));
+}
+function readConfigFile() {
+    try {
+        const parsed = JSON.parse(readFileSync(configFilePath(), "utf8"));
+        return {
+            apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
+            baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : undefined,
+        };
+    }
+    catch {
+        return {}; // file is optional
+    }
+}
+/**
+ * Resolve config. Precedence: environment variables > config file > defaults.
+ * Throws a clear error if no API key can be found.
+ */
+export function loadConfig() {
+    const file = readConfigFile();
+    const apiKey = process.env.TIMESHEETAI_API_KEY ?? file.apiKey;
+    if (!apiKey) {
+        throw new Error("Missing API key. Set TIMESHEETAI_API_KEY (recommended, in your MCP host config) " +
+            `or add { "apiKey": "..." } to ${configFilePath()}.`);
+    }
+    const baseUrl = (process.env.TIMESHEETAI_BASE_URL ??
+        file.baseUrl ??
+        DEFAULT_BASE_URL).replace(/\/+$/, "");
+    return { apiKey, baseUrl };
+}
+/**
+ * The user's local calendar day as YYYY-MM-DD. Intentionally uses local Date
+ * methods: the MCP server runs on the user's machine, so its local day IS the
+ * user's day. The backend then applies wall-clock/floating-time rules to this
+ * explicit date and never guesses a timezone (story Open Design Decision #4).
+ */
+export function localToday() {
+    const d = new Date();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Entry point: connect the TimesheetAI MCP server over stdio. This is what an
+ * MCP host (Codex, Claude Code, Claude Desktop) launches via `npx @timesheetai/mcp`.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Entry point: connect the TimesheetAI MCP server over stdio. This is what an
+ * MCP host (Codex, Claude Code, Claude Desktop) launches via `npx @timesheetai/mcp`.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { describeEndpoint, loadConfig } from "./config.js";
+async function main() {
+    // Load config once and inject it, so the banner and the client agree on the
+    // resolved base URL (no second file/env read).
+    const config = loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs; stdout is the MCP transport channel.
+    // Echo the active endpoint so a tester is never silently on the wrong API —
+    // production is unmarked; alpha/local/other get a visible warning.
+    const ep = describeEndpoint(config.baseUrl);
+    const marker = ep.production ? "" : `  ⚠️  ${ep.label}`;
+    process.stderr.write(`TimesheetAI MCP → ${config.baseUrl}${marker}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err?.message ?? err}\n`);
+    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":";AACA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE3D,KAAK,UAAU,IAAI;IACjB,4EAA4E;IAC5E,+CAA+C;IAC/C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,gEAAgE;IAChE,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC;IACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,MAAM,CAAC,OAAO,GAAG,MAAM,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,OAAO,IAAI,GAAG,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The TimesheetAI MCP server: exposes typed tools that AI agents call to read
+ * projects and log time. A thin client over the authenticated backend API.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Config } from "./config.js";
+export declare function createServer(config?: Config): McpServer;

package/dist/server.js

@@ -0,0 +1,149 @@
+/**
+ * The TimesheetAI MCP server: exposes typed tools that AI agents call to read
+ * projects and log time. A thin client over the authenticated backend API.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { loadConfig, localToday } from "./config.js";
+import { ApiError, TimesheetClient } from "./client.js";
+function ok(data, summary) {
+    const text = summary
+        ? `${summary}\n\n${JSON.stringify(data, null, 2)}`
+        : JSON.stringify(data, null, 2);
+    return { content: [{ type: "text", text }] };
+}
+function fail(err) {
+    if (err instanceof ApiError) {
+        return {
+            content: [{ type: "text", text: `Error [${err.code}]: ${err.message}` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            { type: "text", text: `Error: ${err?.message ?? String(err)}` },
+        ],
+        isError: true,
+    };
+}
+const TIME_DESC = "24-hour wall-clock time, HH:mm (e.g. 13:30).";
+const WORKSPACE_DESC = "Workspace id, name, or slug. Optional when you belong to exactly one workspace.";
+export function createServer(config = loadConfig()) {
+    const client = new TimesheetClient(config);
+    const server = new McpServer({
+        name: "timesheetai",
+        version: "0.1.0",
+    });
+    server.registerTool("list_workspaces", {
+        title: "List workspaces",
+        description: "List the TimesheetAI workspaces your API key can access. Use when a tool reports that a workspace must be specified.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok(await client.listWorkspaces());
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("list_projects", {
+        title: "List projects",
+        description: "List active projects and their active tasks. Call this first to get the projectId and taskId needed by add_time_entry.",
+        inputSchema: {
+            workspace: z.string().describe(WORKSPACE_DESC).optional(),
+        },
+    }, async ({ workspace }) => {
+        try {
+            return ok(await client.listProjects(workspace));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("list_today", {
+        title: "List a day's time entries",
+        description: "List your own time entries for a given day. Defaults to today (this machine's local date) when no date is given.",
+        inputSchema: {
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe("Day to list, YYYY-MM-DD. Defaults to today.")
+                .optional(),
+            workspace: z.string().describe(WORKSPACE_DESC).optional(),
+        },
+    }, async ({ date, workspace }) => {
+        try {
+            const day = date ?? localToday();
+            return ok(await client.listEntries(day, workspace));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    server.registerTool("add_time_entry", {
+        title: "Add a time entry",
+        description: "Log a single time entry. Resolve projectId/taskId via list_projects first. Time is wall-clock; the date defaults to today.",
+        inputSchema: {
+            projectId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Project id from list_projects."),
+            taskId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Task id from list_projects. Optional but recommended.")
+                .optional(),
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe("Entry date, YYYY-MM-DD. Defaults to today.")
+                .optional(),
+            start: z
+                .string()
+                .regex(/^([01]\d|2[0-3]):[0-5]\d$/)
+                .describe(`Start ${TIME_DESC}`),
+            end: z
+                .string()
+                .regex(/^([01]\d|2[0-3]):[0-5]\d$/)
+                .describe(`End ${TIME_DESC} Must be after start.`),
+            description: z
+                .string()
+                .describe("What was worked on.")
+                .optional(),
+            isBillable: z
+                .boolean()
+                .describe("Override billable flag. Defaults to the task/project default.")
+                .optional(),
+            workspace: z.string().describe(WORKSPACE_DESC).optional(),
+            clientRefId: z
+                .string()
+                .uuid()
+                .describe("Idempotency key (UUID). Reuse the SAME value when retrying the same logical add so it is not duplicated. Omit to auto-generate (no retry protection).")
+                .optional(),
+        },
+    }, async ({ projectId, taskId, date, start, end, description, isBillable, workspace, clientRefId }) => {
+        try {
+            const result = await client.addTimeEntry({
+                projectId,
+                taskId,
+                date: date ?? localToday(),
+                start,
+                end,
+                description,
+                isBillable,
+                workspace,
+                clientRefId,
+            });
+            const verb = result.idempotent ? "Already logged" : "Logged";
+            const e = result.entry;
+            return ok(result, `${verb}: ${e.project ?? "?"} / ${e.task ?? "—"} on ${e.date} ${e.start}–${e.end}.`);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOxD,SAAS,EAAE,CAAC,IAAa,EAAE,OAAgB;IACzC,MAAM,IAAI,GAAG,OAAO;QAClB,CAAC,CAAC,GAAG,OAAO,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QAClD,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,SAAS,IAAI,CAAC,GAAY;IACxB,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;YACxE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAW,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE;SAC3E;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,8CAA8C,CAAC;AACjE,MAAM,cAAc,GAClB,iFAAiF,CAAC;AAEpF,MAAM,UAAU,YAAY,CAAC,SAAiB,UAAU,EAAE;IACxD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IAE3C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EACT,sHAAsH;QACxH,WAAW,EAAE,EAAE;KAChB,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,MAAM,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,wHAAwH;QAC1H,WAAW,EAAE;YACX,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;SAC1D;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACtB,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,kHAAkH;QACpH,WAAW,EAAE;YACX,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,6CAA6C,CAAC;iBACvD,QAAQ,EAAE;YACb,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;SAC1D;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE;QAC5B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,CAAC;YACjC,OAAO,EAAE,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,4HAA4H;QAC9H,WAAW,EAAE;YACX,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CAAC,gCAAgC,CAAC;YAC7C,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CAAC,uDAAuD,CAAC;iBACjE,QAAQ,EAAE;YACb,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,4CAA4C,CAAC;iBACtD,QAAQ,EAAE;YACb,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,KAAK,CAAC,2BAA2B,CAAC;iBAClC,QAAQ,CAAC,SAAS,SAAS,EAAE,CAAC;YACjC,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,KAAK,CAAC,2BAA2B,CAAC;iBAClC,QAAQ,CAAC,OAAO,SAAS,uBAAuB,CAAC;YACpD,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,QAAQ,CAAC,qBAAqB,CAAC;iBAC/B,QAAQ,EAAE;YACb,UAAU,EAAE,CAAC;iBACV,OAAO,EAAE;iBACT,QAAQ,CAAC,+DAA+D,CAAC;iBACzE,QAAQ,EAAE;YACb,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;YACzD,WAAW,EAAE,CAAC;iBACX,MAAM,EAAE;iBACR,IAAI,EAAE;iBACN,QAAQ,CACP,uJAAuJ,CACxJ;iBACA,QAAQ,EAAE;SACd;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,EAAE;QACjG,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;gBACvC,SAAS;gBACT,MAAM;gBACN,IAAI,EAAE,IAAI,IAAI,UAAU,EAAE;gBAC1B,KAAK;gBACL,GAAG;gBACH,WAAW;gBACX,UAAU;gBACV,SAAS;gBACT,WAAW;aACZ,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC7D,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;YACvB,OAAO,EAAE,CACP,MAAM,EACN,GAAG,IAAI,KAAK,CAAC,CAAC,OAAO,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG,CACpF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@timesheetai/mcp",
+  "version": "0.1.0-alpha.1",
+  "description": "Model Context Protocol server for TimesheetAI — log time from AI agents.",
+  "license": "MIT",
+  "comment:dist-tag": "Published under the `alpha` npm dist-tag while DEFAULT_BASE_URL points at alpha. Install with `@timesheetai/mcp@alpha`. At production launch: flip DEFAULT_BASE_URL to production, bump to a stable version, and publish to `latest`.",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "type": "module",
+  "bin": {
+    "timesheetai-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}