mcp-intervals 1.5.1 → 1.6.0

package/README.md

@@ -111,16 +111,43 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ## Available Tools
 
-| Tool               | Description                                                                  |
-| ------------------ | ---------------------------------------------------------------------------- |
-| `get_task`         | Get task details by local ID or Intervals URL                                |
-| `update_task`      | Update task status, assignee, priority, title, description, due date, owner  |
-| `add_task_note`    | Add a comment/note to a task (supports HTML)                                 |
-| `get_task_notes`   | Retrieve all comments/notes on a task                                        |
-| `add_time_entry`   | Add a time entry to a task (billable/unbillable with work type)              |
-| `get_time_entries` | Retrieve time entries (filter by task, date range)                           |
-| `get_project`      | Get project details (name, client, dates, budget)                            |
-| `get_milestone`    | Get milestone details (title, due date, progress)                            |
+104 tools covering the full Intervals API. Tasks are addressed by the **local task ID** shown in the web UI (or a task URL for `get_task`); every other record uses its numeric API ID.
+
+**Permissions:** some collection endpoints (`worktype`, `invoice`, `expense`, `module`, `payment`) return 403 depending on the user's permission group. Project-scoped alternatives exist: `get_project_worktypes` and `get_project_modules`.
+
+| Area | Tools |
+| ---- | ----- |
+| Tasks | `get_task`, `get_tasks`, `create_task`, `update_task`, `delete_task`, `get_task_statuses`, `get_task_priorities` |
+| Task notes | `get_task_notes`, `add_task_note`, `update_task_note`, `delete_task_note` |
+| Task filters | `get_task_filters`, `get_task_filter`, `create_task_filter`, `update_task_filter` |
+| Time | `add_time_entry`, `get_time_entries`, `update_time_entry`, `delete_time_entry`, `get_worktypes` |
+| Timers | `get_timers`, `start_timer`, `stop_timer` |
+| Expenses | `get_expenses`, `create_expense` |
+| Projects | `get_project`, `get_projects`, `create_project`, `update_project` |
+| Project team | `get_project_team`, `add_project_team_member`, `remove_project_team_member` |
+| Project modules | `get_project_modules`, `add_project_module`, `update_project_module`, `remove_project_module` |
+| Project work types | `get_project_worktypes`, `add_project_worktype`, `update_project_worktype`, `remove_project_worktype` |
+| Project labels | `get_project_labels`, `get_project_label`, `create_project_label`, `update_project_label` |
+| Project notes | `get_project_notes`, `get_project_note`, `create_project_note`, `update_project_note`, `delete_project_note` |
+| Default modules | `get_modules`, `get_module`, `create_module`, `update_module` |
+| Milestones | `get_milestone`, `get_milestones`, `create_milestone`, `update_milestone` |
+| Milestone notes | `get_milestone_notes`, `create_milestone_note`, `update_milestone_note`, `delete_milestone_note` |
+| Requests | `get_requests`, `get_request`, `create_request`, `update_request`, `delete_request` |
+| Clients | `get_clients`, `get_client`, `create_client`, `update_client` |
+| People | `get_people`, `get_person`, `get_me`, `get_groups`, `get_quota` |
+| Contacts | `get_contact_types`, `get_contact_descriptors`, `get_person_contacts`, `create_person_contact`, `update_person_contact`, `delete_person_contact` |
+| Invoices | `get_invoices`, `get_invoice`, `create_invoice`, `get_invoice_terms` |
+| Invoice items | `get_invoice_items`, `create_invoice_item`, `update_invoice_item`, `delete_invoice_item` |
+| Invoice notes | `get_invoice_notes`, `create_invoice_note`, `update_invoice_note`, `delete_invoice_note` |
+| Payments | `get_payments`, `get_payment`, `create_payment`, `update_payment`, `delete_payment`, `get_payment_types` |
+| Documents | `get_documents`, `get_document`, `download_document` (images inline, PDF text), `create_document`, `update_document` |
+
+### Notifications
+
+Every write tool (create/update/delete) accepts two optional booleans:
+
+- `send_notifications` - sends `X-Intervals-Send-Notifications: t`. **Emails are not sent unless this is true** (the API default).
+- `disable_action_notes` - sends `X-Intervals-Disable-Action-Notes: t` to suppress the automatic action notes Intervals adds to tasks and milestones.
 
 ## Resources
 

package/dist/client.d.ts

@@ -1,7 +1,18 @@
-export interface IntervalsRequestOptions {
+export type QueryParams = Record<string, string | number | boolean | undefined>;
+/**
+ * Opt-in notification controls for write requests. The Intervals API sends no
+ * emails by default, so nothing is added unless a flag is explicitly true.
+ */
+export interface NotificationOptions {
+    /** Maps to `X-Intervals-Send-Notifications: t` (emails are NOT sent otherwise). */
+    sendNotifications?: boolean;
+    /** Maps to `X-Intervals-Disable-Action-Notes: t` (suppress automatic action notes). */
+    disableActionNotes?: boolean;
+}
+export interface IntervalsRequestOptions extends NotificationOptions {
     method?: "GET" | "POST" | "PUT" | "DELETE";
     body?: Record<string, unknown>;
-    params?: Record<string, string | number | boolean>;
+    params?: QueryParams;
 }
 export declare class IntervalsClient {
     private baseUrl;
@@ -9,19 +20,19 @@ export declare class IntervalsClient {
     constructor(apiToken: string);
     private request;
     private requestBinary;
+    get(path: string, params?: QueryParams): Promise<Record<string, unknown>>;
+    post(path: string, body: Record<string, unknown>, notify?: NotificationOptions): Promise<Record<string, unknown>>;
+    put(path: string, body: Record<string, unknown>, notify?: NotificationOptions): Promise<Record<string, unknown>>;
+    delete(path: string, params?: QueryParams, notify?: NotificationOptions): Promise<Record<string, unknown>>;
     getTask(id: number): Promise<Record<string, unknown>>;
     getTaskByLocalId(localId: number): Promise<Record<string, unknown>>;
     resolveTaskId(localId: number): Promise<number>;
-    updateTask(id: number, fields: Record<string, unknown>): Promise<Record<string, unknown>>;
-    getTaskNotes(taskId: number): Promise<Record<string, unknown>>;
-    addTaskNote(taskId: number, note: string, isPublic?: boolean): Promise<Record<string, unknown>>;
+    updateTask(id: number, fields: Record<string, unknown>, notify?: NotificationOptions): Promise<Record<string, unknown>>;
+    getTaskNotes(taskId: number, filters?: QueryParams): Promise<Record<string, unknown>>;
+    addTaskNote(taskId: number, note: string, isPublic?: boolean, notify?: NotificationOptions): Promise<Record<string, unknown>>;
     getProject(id: number): Promise<Record<string, unknown>>;
     getMilestone(id: number): Promise<Record<string, unknown>>;
-    getDocuments(params?: {
-        taskid?: number;
-        projectid?: number;
-        personid?: number;
-    }): Promise<Record<string, unknown>>;
+    getDocuments(params?: QueryParams): Promise<Record<string, unknown>>;
     getDocument(id: number): Promise<Record<string, unknown>>;
     downloadDocument(id: number): Promise<{
         buffer: ArrayBuffer;
@@ -37,13 +48,10 @@ export declare class IntervalsClient {
         time: number;
         billable: boolean;
         description?: string;
-    }): Promise<Record<string, unknown>>;
-    getTimeEntries(params?: {
-        taskid?: number;
         personid?: number;
-        datebegin?: string;
-        dateend?: string;
-    }): Promise<Record<string, unknown>>;
+        moduleid?: number;
+    }, notify?: NotificationOptions): Promise<Record<string, unknown>>;
+    getTimeEntries(params?: QueryParams): Promise<Record<string, unknown>>;
     getMe(): Promise<{
         personid: number;
     }>;

package/dist/client.js

@@ -1,3 +1,15 @@
+function buildQueryString(params) {
+    if (!params)
+        return "";
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        searchParams.set(key, String(value));
+    }
+    const query = searchParams.toString();
+    return query ? `?${query}` : "";
+}
 export class IntervalsClient {
     baseUrl = "https://api.myintervals.com";
     authHeader;
@@ -6,19 +18,18 @@ export class IntervalsClient {
             "Basic " + Buffer.from(`${apiToken}:X`).toString("base64");
     }
     async request(path, options = {}) {
-        const { method = "GET", body, params } = options;
-        let url = `${this.baseUrl}${path}`;
-        if (params) {
-            const searchParams = new URLSearchParams();
-            for (const [key, value] of Object.entries(params)) {
-                searchParams.set(key, String(value));
-            }
-            url += `?${searchParams.toString()}`;
-        }
+        const { method = "GET", body, params, sendNotifications, disableActionNotes, } = options;
+        const url = `${this.baseUrl}${path}${buildQueryString(params)}`;
         const headers = {
             Authorization: this.authHeader,
             Accept: "application/json",
         };
+        if (sendNotifications) {
+            headers["X-Intervals-Send-Notifications"] = "t";
+        }
+        if (disableActionNotes) {
+            headers["X-Intervals-Disable-Action-Notes"] = "t";
+        }
         const fetchOptions = { method, headers };
         if (body) {
             headers["Content-Type"] = "application/json";
@@ -29,29 +40,52 @@ export class IntervalsClient {
             const text = await response.text();
             throw new Error(`Intervals API error ${response.status}: ${text.slice(0, 500)}`);
         }
-        return response.json();
+        // Successful writes (e.g. DELETE) may return an empty body.
+        const text = await response.text();
+        if (!text.trim())
+            return {};
+        return JSON.parse(text);
     }
     async requestBinary(path, params) {
-        let url = `${this.baseUrl}${path}`;
-        if (params) {
-            const searchParams = new URLSearchParams();
-            for (const [key, value] of Object.entries(params)) {
-                searchParams.set(key, String(value));
-            }
-            url += `?${searchParams.toString()}`;
-        }
+        const url = `${this.baseUrl}${path}${buildQueryString(params)}`;
         const response = await fetch(url, {
             method: "GET",
             headers: { Authorization: this.authHeader },
         });
         if (!response.ok) {
             const text = await response.text();
-            throw new Error(`Intervals API error ${response.status}: ${text}`);
+            throw new Error(`Intervals API error ${response.status}: ${text.slice(0, 500)}`);
         }
         const buffer = await response.arrayBuffer();
         const contentType = response.headers.get("content-type") || "application/octet-stream";
         return { buffer, contentType };
     }
+    // --- Generic verbs (used by the declarative endpoint tools) ---
+    // Paths are given without the trailing slash, e.g. "/client" or "/client/12".
+    get(path, params) {
+        return this.request(`${path}/`, { params });
+    }
+    post(path, body, notify = {}) {
+        return this.request(`${path}/`, {
+            method: "POST",
+            body,
+            ...notify,
+        });
+    }
+    put(path, body, notify = {}) {
+        return this.request(`${path}/`, {
+            method: "PUT",
+            body,
+            ...notify,
+        });
+    }
+    delete(path, params, notify = {}) {
+        return this.request(`${path}/`, {
+            method: "DELETE",
+            params,
+            ...notify,
+        });
+    }
     // --- Task ---
     async getTask(id) {
         const data = await this.request(`/task/${id}/`);
@@ -68,19 +102,20 @@ export class IntervalsClient {
         const task = await this.getTaskByLocalId(localId);
         return Number(task.id);
     }
-    async updateTask(id, fields) {
-        const data = await this.request(`/task/${id}/`, { method: "PUT", body: fields });
+    async updateTask(id, fields, notify = {}) {
+        const data = await this.request(`/task/${id}/`, { method: "PUT", body: fields, ...notify });
         return data;
     }
     // --- Task Notes ---
-    async getTaskNotes(taskId) {
-        const data = await this.request(`/tasknote/`, { params: { taskid: taskId } });
+    async getTaskNotes(taskId, filters = {}) {
+        const data = await this.request(`/tasknote/`, { params: { ...filters, taskid: taskId } });
         return data;
     }
-    async addTaskNote(taskId, note, isPublic = true) {
+    async addTaskNote(taskId, note, isPublic = true, notify = {}) {
         const data = await this.request(`/tasknote/`, {
             method: "POST",
             body: { taskid: taskId, note, public: isPublic },
+            ...notify,
         });
         return data;
     }
@@ -97,7 +132,7 @@ export class IntervalsClient {
     // --- Documents ---
     async getDocuments(params = {}) {
         const data = await this.request(`/document/`, {
-            params: params,
+            params,
         });
         return data;
     }
@@ -123,10 +158,13 @@ export class IntervalsClient {
         return data;
     }
     // --- Time Entries ---
-    async addTimeEntry(fields) {
-        // First get the current user's person ID
-        const me = await this.getMe();
-        const personid = me.personid;
+    async addTimeEntry(fields, notify = {}) {
+        // Default to the current user's person ID
+        let personid = fields.personid;
+        if (personid === undefined) {
+            const me = await this.getMe();
+            personid = me.personid;
+        }
         if (typeof personid !== "number") {
             throw new Error("Could not determine current user's person ID from Intervals /me/ response.");
         }
@@ -139,13 +177,15 @@ export class IntervalsClient {
                 date: fields.date,
                 time: fields.time,
                 billable: fields.billable,
+                ...(fields.moduleid !== undefined && { moduleid: fields.moduleid }),
                 ...(fields.description && { description: fields.description }),
             },
+            ...notify,
         });
         return data;
     }
     async getTimeEntries(params = {}) {
-        const data = await this.request(`/time/`, { params: params });
+        const data = await this.request(`/time/`, { params });
         return data;
     }
     // --- Me (current user) ---

package/dist/index.js

@@ -11,7 +11,7 @@ async function startServer() {
     const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
     const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
     const { IntervalsClient } = await import("./client.js");
-    const { registerTools } = await import("./tools.js");
+    const { registerTools } = await import("./tools/index.js");
     const { registerResources } = await import("./resources.js");
     const { createRequire } = await import("node:module");
     // Read version from package.json so it never drifts from the published one.

package/dist/tools/billing.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { IntervalsClient } from "../client.js";
+export declare function registerBillingTools(server: McpServer, client: IntervalsClient): void;

package/dist/tools/billing.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import { limitParam, offsetParam, registerEndpoints } from "./helpers.js";
+const itemFields = {
+    invoiceid: z.number().describe("Invoice ID (use get_invoices)"),
+    name: z.string().describe("Line item name (max 255 characters)"),
+    amount: z.number().describe("Line item amount"),
+    description: z.string().describe("Line item description"),
+    quantity: z.number().describe("Quantity"),
+    rate: z.number().describe("Rate"),
+};
+const invoiceNoteFields = {
+    invoiceid: z.number().describe("Invoice ID (use get_invoices)"),
+    title: z.string().describe("Note title (max 255 characters)"),
+    note: z.string().describe("Note body"),
+    date: z.string().describe("Note date (YYYY-MM-DD HH:MM:SS)"),
+};
+const paymentFields = {
+    projectid: z.number().describe("Project ID (use get_projects)"),
+    date: z.string().describe("Payment date (YYYY-MM-DD)"),
+    amount: z.number().describe("Payment amount"),
+    typeid: z.number().describe("Payment type ID (use get_payment_types)"),
+    invoiceid: z.number().describe("Invoice ID to apply the payment to (use get_invoices)"),
+    reference: z.string().describe("Reference number (max 35 characters)"),
+    note: z.string().describe("Payment note (max 255 characters)"),
+};
+const specs = [
+    // --- Invoices ---
+    {
+        name: "get_invoices",
+        description: "List invoices, optionally filtered by client or status (draft, sent, paid).",
+        method: "GET",
+        path: "/invoice",
+        schema: {
+            clientid: z.number().optional().describe("Filter by client ID"),
+            status: z.string().optional().describe("Invoice status: draft, sent, or paid"),
+            limit: limitParam,
+            offset: offsetParam,
+        },
+    },
+    {
+        name: "get_invoice",
+        description: "Get full details of a single invoice by ID.",
+        method: "GET",
+        path: "/invoice",
+        idParam: "invoiceId",
+        schema: { invoiceId: z.number().describe("Invoice ID") },
+    },
+    {
+        name: "create_invoice",
+        description: "Create an invoice for a project. Requires project, date, term ID, and title.",
+        method: "POST",
+        path: "/invoice",
+        schema: {
+            projectid: z.number().describe("Project ID the invoice is for (use get_projects)"),
+            date: z.string().describe("Invoice date (YYYY-MM-DD)"),
+            termid: z.number().describe("Invoice term ID, e.g. Net 30 (use get_invoice_terms)"),
+            title: z.string().describe("Invoice title (max 255 characters)"),
+            description: z.string().optional().describe("Invoice description/notes"),
+            termother: z.string().optional().describe("Custom payment terms text (max 255 characters)"),
+            termotherdatedue: z.string().optional().describe("Custom due date when using termother (YYYY-MM-DD)"),
+            addressfrom: z.string().optional().describe("From address on the invoice"),
+            addressto: z.string().optional().describe("To address on the invoice"),
+            purchaseorder: z.string().optional().describe("Purchase order number (max 55 characters)"),
+            tax: z.number().optional().describe("Tax rate percentage"),
+            datebegin: z.string().optional().describe("Billing period start date (YYYY-MM-DD)"),
+            dateend: z.string().optional().describe("Billing period end date (YYYY-MM-DD)"),
+        },
+    },
+    {
+        name: "get_invoice_terms",
+        description: "List invoice payment terms (e.g. Net 30, Upon Receipt). Use the IDs when creating invoices.",
+        method: "GET",
+        path: "/invoiceterm",
+        schema: {},
+    },
+    // --- Invoice items ---
+    {
+        name: "get_invoice_items",
+        description: "List line items for an invoice.",
+        method: "GET",
+        path: "/invoiceitem",
+        schema: {
+            invoiceid: z.number().describe("Invoice ID to list items for"),
+            limit: limitParam,
+            offset: offsetParam,
+        },
+    },
+    {
+        name: "create_invoice_item",
+        description: "Add a line item to an invoice.",
+        method: "POST",
+        path: "/invoiceitem",
+        schema: {
+            invoiceid: itemFields.invoiceid,
+            name: itemFields.name,
+            amount: itemFields.amount,
+            description: itemFields.description.optional(),
+            quantity: itemFields.quantity.optional(),
+            rate: itemFields.rate.optional(),
+        },
+    },
+    {
+        name: "update_invoice_item",
+        description: "Update an invoice line item. Only custom line items support quantity, rate, and amount changes.",
+        method: "PUT",
+        path: "/invoiceitem",
+        idParam: "invoiceItemId",
+        schema: {
+            invoiceItemId: z.number().describe("Invoice item ID to update"),
+            invoiceid: itemFields.invoiceid.optional(),
+            name: itemFields.name.optional(),
+            amount: itemFields.amount.optional(),
+            description: itemFields.description.optional(),
+            quantity: itemFields.quantity.optional(),
+            rate: itemFields.rate.optional(),
+        },
+    },
+    {
+        name: "delete_invoice_item",
+        description: "Delete a custom invoice line item by ID. Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/invoiceitem",
+        idParam: "invoiceItemId",
+        schema: { invoiceItemId: z.number().describe("Invoice item ID to delete") },
+    },
+    // --- Invoice notes ---
+    {
+        name: "get_invoice_notes",
+        description: "List invoice notes, optionally for a single invoice.",
+        method: "GET",
+        path: "/invoicenote",
+        schema: {
+            invoiceid: z.number().optional().describe("Filter by invoice ID"),
+            limit: limitParam,
+            offset: offsetParam,
+        },
+    },
+    {
+        name: "create_invoice_note",
+        description: "Add a note to an invoice.",
+        method: "POST",
+        path: "/invoicenote",
+        schema: {
+            invoiceid: invoiceNoteFields.invoiceid,
+            title: invoiceNoteFields.title,
+            note: invoiceNoteFields.note.optional(),
+            date: invoiceNoteFields.date.optional(),
+        },
+    },
+    {
+        name: "update_invoice_note",
+        description: "Update an invoice note. Only provide fields you want to change.",
+        method: "PUT",
+        path: "/invoicenote",
+        idParam: "invoiceNoteId",
+        schema: {
+            invoiceNoteId: z.number().describe("Invoice note ID to update"),
+            invoiceid: invoiceNoteFields.invoiceid.optional(),
+            title: invoiceNoteFields.title.optional(),
+            note: invoiceNoteFields.note.optional(),
+            date: invoiceNoteFields.date.optional(),
+        },
+    },
+    {
+        name: "delete_invoice_note",
+        description: "Delete an invoice note by ID. Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/invoicenote",
+        idParam: "invoiceNoteId",
+        schema: { invoiceNoteId: z.number().describe("Invoice note ID to delete") },
+    },
+    // --- Payments ---
+    {
+        name: "get_payments",
+        description: "List payments, optionally filtered by project or invoice.",
+        method: "GET",
+        path: "/payment",
+        schema: {
+            projectid: z.number().optional().describe("Filter by project ID"),
+            invoiceid: z.number().optional().describe("Filter by invoice ID"),
+            limit: limitParam,
+            offset: offsetParam,
+        },
+    },
+    {
+        name: "get_payment",
+        description: "Get full details of a single payment by ID.",
+        method: "GET",
+        path: "/payment",
+        idParam: "paymentId",
+        schema: { paymentId: z.number().describe("Payment ID") },
+    },
+    {
+        name: "create_payment",
+        description: "Record a payment against a project.",
+        method: "POST",
+        path: "/payment",
+        schema: {
+            projectid: paymentFields.projectid,
+            date: paymentFields.date,
+            amount: paymentFields.amount,
+            typeid: paymentFields.typeid,
+            invoiceid: paymentFields.invoiceid.optional(),
+            reference: paymentFields.reference.optional(),
+            note: paymentFields.note.optional(),
+        },
+    },
+    {
+        name: "update_payment",
+        description: "Update a payment. Only provide fields you want to change.",
+        method: "PUT",
+        path: "/payment",
+        idParam: "paymentId",
+        schema: {
+            paymentId: z.number().describe("Payment ID to update"),
+            projectid: paymentFields.projectid.optional(),
+            date: paymentFields.date.optional(),
+            amount: paymentFields.amount.optional(),
+            typeid: paymentFields.typeid.optional(),
+            invoiceid: paymentFields.invoiceid.optional(),
+            reference: paymentFields.reference.optional(),
+            note: paymentFields.note.optional(),
+        },
+    },
+    {
+        name: "delete_payment",
+        description: "Delete a payment by ID (Administrator only). Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/payment",
+        idParam: "paymentId",
+        schema: { paymentId: z.number().describe("Payment ID to delete") },
+    },
+    {
+        name: "get_payment_types",
+        description: "List payment types (e.g. Cash, Check, Credit Card). Use the IDs when creating payments.",
+        method: "GET",
+        path: "/paymenttype",
+        schema: {},
+    },
+];
+export function registerBillingTools(server, client) {
+    registerEndpoints(server, client, specs);
+}

package/dist/tools/core.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { IntervalsClient } from "../client.js";
+export declare function registerCoreTools(server: McpServer, client: IntervalsClient): void;