mcp-intervals 1.5.0 → 1.6.0

package/dist/tools/core.js

@@ -0,0 +1,430 @@
+import { z } from "zod";
+import { PDFParse } from "pdf-parse";
+import { idOrList, limitParam, notificationShape, offsetParam, splitNotifications, } from "./helpers.js";
+import { parseTaskIdFromUrl, getMimeTypeFromFilename, isImageMimeType, } from "../utils.js";
+// Cap on inline-rendered downloads (images/PDFs). Base64 inflates payload
+// ~33% and the result is fed into the model context, so guard against
+// flooding memory/context with oversized attachments.
+const MAX_INLINE_DOWNLOAD_BYTES = 25 * 1024 * 1024; // 25 MB
+const NOTIFICATION_NOTE = " Emails are not sent unless send_notifications is true.";
+export function registerCoreTools(server, client) {
+    // --- get_task ---
+    server.tool("get_task", "Retrieve full details of an Intervals task. Accepts a task URL (e.g. https://<subdomain>.intervalsonline.com/tasks/view/12345) or a numeric local task ID (the ID shown in the Intervals web UI).", {
+        task: z
+            .string()
+            .describe("Intervals task URL or numeric local task ID (as shown in the web UI)"),
+    }, async ({ task }) => {
+        const localId = parseTaskIdFromUrl(task);
+        const data = await client.getTaskByLocalId(localId);
+        const internalId = Number(data.id);
+        const content = [{ type: "text", text: JSON.stringify(data, null, 2) }];
+        // Fetch associated documents
+        try {
+            const docsData = await client.getDocuments({ taskid: internalId });
+            const documents = docsData.document;
+            if (Array.isArray(documents) && documents.length > 0) {
+                const docSummary = documents.map((doc) => ({
+                    id: doc.id,
+                    filename: doc.filename,
+                    title: doc.title,
+                    dateCreated: doc.datecreated,
+                    size: doc.filesize,
+                }));
+                content.push({
+                    type: "text",
+                    text: `\n--- Attached Documents (${documents.length}) ---\n` +
+                        JSON.stringify(docSummary, null, 2) +
+                        `\n\nUse the download_document tool with the document ID to view image attachments.`,
+                });
+            }
+        }
+        catch {
+            // Silently ignore document fetch failures
+        }
+        return { content };
+    });
+    // --- update_task ---
+    server.tool("update_task", "Update fields on an Intervals task (status, assignee, priority, title, description, dates, owner, project, module, milestone, followers, estimate)." +
+        NOTIFICATION_NOTE, {
+        taskId: z.number().describe("The local task ID (as shown in the Intervals web UI)"),
+        statusid: z
+            .number()
+            .optional()
+            .describe("New status ID (use intervals://statuses resource for valid IDs)"),
+        assigneeid: idOrList
+            .optional()
+            .describe("New assignee person ID, or comma-delimited list of IDs"),
+        priorityid: z
+            .number()
+            .optional()
+            .describe("New priority ID (use intervals://priorities resource for valid IDs)"),
+        title: z.string().optional().describe("New task title"),
+        summary: z
+            .string()
+            .optional()
+            .describe('New task description/summary (HTML is accepted). IMPORTANT: For checklists, use Intervals-specific HTML — do NOT use emojis (✅, ☐) or markdown checkboxes. Use: <ul class="checklist"><li class="checklist-checked">Done item</li><li>Pending item</li></ul>. Checked items get class="checklist-checked", unchecked items have no class.'),
+        datedue: z
+            .string()
+            .optional()
+            .describe("New due date in YYYY-MM-DD format"),
+        ownerid: idOrList
+            .optional()
+            .describe("New owner person ID, or comma-delimited list of IDs"),
+        projectid: z.number().optional().describe("New project ID"),
+        moduleid: z.number().optional().describe("New module ID"),
+        milestoneid: z.number().optional().describe("New milestone ID"),
+        followerid: idOrList
+            .optional()
+            .describe("Follower person ID, or comma-delimited list of IDs"),
+        estimate: z.number().optional().describe("Estimated hours"),
+        dateopen: z.string().optional().describe("Open date in YYYY-MM-DD format"),
+        dateclosed: z
+            .string()
+            .optional()
+            .describe("Closed date in YYYY-MM-DD format (set to close the task)"),
+        ...notificationShape,
+    }, async ({ taskId, ...args }) => {
+        const { fields, notify } = splitNotifications(args);
+        // Remove undefined fields
+        const updateData = {};
+        for (const [key, value] of Object.entries(fields)) {
+            if (value !== undefined) {
+                updateData[key] = value;
+            }
+        }
+        if (Object.keys(updateData).length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No fields provided to update.",
+                    },
+                ],
+            };
+        }
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.updateTask(internalId, updateData, notify);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- add_task_note ---
+    server.tool("add_task_note", "Add a comment/note to an Intervals task." + NOTIFICATION_NOTE, {
+        taskId: z.number().describe("The local task ID (as shown in the Intervals web UI)"),
+        note: z
+            .string()
+            .describe('The note content (HTML is accepted). IMPORTANT: For checklists, use Intervals-specific HTML — do NOT use emojis (✅, ☐) or markdown checkboxes. Use: <ul class="checklist"><li class="checklist-checked">Done item</li><li>Pending item</li></ul>. Checked items get class="checklist-checked", unchecked items have no class.'),
+        isPublic: z
+            .boolean()
+            .default(true)
+            .describe("Whether the note is visible to executive users (defaults to true)"),
+        ...notificationShape,
+    }, async ({ taskId, note, isPublic, ...flags }) => {
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.addTaskNote(internalId, note, isPublic, splitNotifications(flags).notify);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_task_notes ---
+    server.tool("get_task_notes", "Retrieve comments/notes on an Intervals task.", {
+        taskId: z
+            .number()
+            .describe("The local task ID (as shown in the Intervals web UI)"),
+        authorid: z.number().optional().describe("Filter by author person ID"),
+        public: z.boolean().optional().describe("Filter by public notes"),
+        datebegin: z.string().optional().describe("Start date filter in YYYY-MM-DD format"),
+        dateend: z.string().optional().describe("End date filter in YYYY-MM-DD format"),
+        limit: limitParam,
+        offset: offsetParam,
+    }, async ({ taskId, ...filters }) => {
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.getTaskNotes(internalId, filters);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_project ---
+    server.tool("get_project", "Retrieve details of an Intervals project (name, client, dates, budget, description).", {
+        projectId: z
+            .number()
+            .describe("The numeric project ID"),
+    }, async ({ projectId }) => {
+        const data = await client.getProject(projectId);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_milestone ---
+    server.tool("get_milestone", "Retrieve details of an Intervals milestone (title, due date, progress, description).", {
+        milestoneId: z
+            .number()
+            .describe("The numeric milestone ID"),
+    }, async ({ milestoneId }) => {
+        const data = await client.getMilestone(milestoneId);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- add_time_entry ---
+    server.tool("add_time_entry", "Add a time entry to an Intervals task. Records time worked as billable or unbillable with a specific work type. Defaults to the current user." + NOTIFICATION_NOTE, {
+        taskId: z
+            .number()
+            .describe("The local task ID (as shown in the Intervals web UI)"),
+        worktypeid: z
+            .number()
+            .describe("Work type ID (use intervals://worktypes resource for valid IDs)"),
+        date: z
+            .string()
+            .describe("Date of the time entry in YYYY-MM-DD format"),
+        time: z
+            .number()
+            .describe("Time worked in decimal hours (e.g., 1.5 for 1 hour 30 minutes)"),
+        billable: z
+            .boolean()
+            .describe("Whether the time is billable (true) or unbillable (false)"),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional description of work performed"),
+        personid: z
+            .number()
+            .optional()
+            .describe("Person ID to log the time for (defaults to the current user)"),
+        moduleid: z.number().optional().describe("Optional module ID"),
+        ...notificationShape,
+    }, async ({ taskId, worktypeid, date, time, billable, description, personid, moduleid, ...flags }) => {
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.addTimeEntry({
+            taskid: internalId,
+            worktypeid,
+            date,
+            time,
+            billable,
+            description,
+            personid,
+            moduleid,
+        }, splitNotifications(flags).notify);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_time_entries ---
+    server.tool("get_time_entries", "Retrieve time entries from Intervals. Can filter by task, person, project, billable status, or date range.", {
+        taskId: z
+            .number()
+            .optional()
+            .describe("Filter by local task ID (as shown in the Intervals web UI)"),
+        datebegin: z
+            .string()
+            .optional()
+            .describe("Start date filter in YYYY-MM-DD format"),
+        dateend: z
+            .string()
+            .optional()
+            .describe("End date filter in YYYY-MM-DD format"),
+        personid: z.number().optional().describe("Filter by person ID"),
+        projectid: z.number().optional().describe("Filter by project ID"),
+        billable: z.boolean().optional().describe("Filter by billable status"),
+        limit: limitParam,
+        offset: offsetParam,
+    }, async ({ taskId, ...filters }) => {
+        let internalTaskId;
+        if (taskId) {
+            internalTaskId = await client.resolveTaskId(taskId);
+        }
+        const data = await client.getTimeEntries({
+            taskid: internalTaskId,
+            ...filters,
+        });
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_documents ---
+    server.tool("get_documents", "List documents/attachments from Intervals. Can filter by task, project, or person. Returns document metadata (filename, title, size, dates) but not file contents. Use download_document to retrieve file contents.", {
+        taskId: z
+            .number()
+            .optional()
+            .describe("Filter by local task ID (as shown in the Intervals web UI)"),
+        projectId: z.number().optional().describe("Filter by project ID"),
+        personId: z.number().optional().describe("Filter by person ID"),
+        milestoneid: z.number().optional().describe("Filter by milestone ID"),
+        clientid: z.number().optional().describe("Filter by client ID"),
+        search: z.string().optional().describe("Search text"),
+        public: z.boolean().optional().describe("Filter by public documents"),
+        limit: limitParam,
+        offset: offsetParam,
+    }, async ({ taskId, projectId, personId, ...filters }) => {
+        let internalTaskId;
+        if (taskId) {
+            internalTaskId = await client.resolveTaskId(taskId);
+        }
+        const data = await client.getDocuments({
+            taskid: internalTaskId,
+            projectid: projectId,
+            personid: personId,
+            ...filters,
+        });
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- download_document ---
+    server.tool("download_document", "Download a document from Intervals. For images (png, jpg, gif, webp, bmp), returns the image inline so it can be viewed directly. For PDFs, extracts and returns the text content. For other file types, returns the document metadata.", {
+        documentId: z
+            .number()
+            .describe("The numeric document ID from Intervals"),
+    }, async ({ documentId }) => {
+        // Get document metadata to know the filename
+        const docData = await client.getDocument(documentId);
+        const docField = docData.document;
+        let document;
+        if (Array.isArray(docField)) {
+            if (docField.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No document found with ID ${documentId}.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            document = docField[0];
+        }
+        else if (docField && typeof docField === "object") {
+            document = docField;
+        }
+        else {
+            document = docData;
+        }
+        const filename = document.filename || document.title || "unknown";
+        const title = document.title || filename;
+        // Reject oversized files before downloading them into memory.
+        const reportedSize = Number(document.filesize);
+        if (Number.isFinite(reportedSize) &&
+            reportedSize > MAX_INLINE_DOWNLOAD_BYTES) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Document "${title}" (${filename}) is ${(reportedSize / (1024 * 1024)).toFixed(2)} MB, exceeding the ${MAX_INLINE_DOWNLOAD_BYTES / (1024 * 1024)} MB inline limit. Download it directly from Intervals instead.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const imageMimeType = getMimeTypeFromFilename(filename);
+        if (imageMimeType && isImageMimeType(imageMimeType)) {
+            try {
+                const { buffer } = await client.downloadDocument(documentId);
+                if (buffer.byteLength > MAX_INLINE_DOWNLOAD_BYTES) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Document "${title}" (${filename}) is ${(buffer.byteLength / (1024 * 1024)).toFixed(2)} MB, exceeding the ${MAX_INLINE_DOWNLOAD_BYTES / (1024 * 1024)} MB inline limit. Download it directly from Intervals instead.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const base64 = Buffer.from(buffer).toString("base64");
+                const sizeMB = buffer.byteLength / (1024 * 1024);
+                const content = [
+                    {
+                        type: "text",
+                        text: `Document: ${title} (${filename}, ${sizeMB.toFixed(2)} MB)`,
+                    },
+                ];
+                if (imageMimeType === "image/svg+xml") {
+                    const svgText = new TextDecoder().decode(buffer);
+                    content.push({
+                        type: "text",
+                        text: `SVG content:\n${svgText}`,
+                    });
+                }
+                else {
+                    content.push({
+                        type: "image",
+                        data: base64,
+                        mimeType: imageMimeType,
+                    });
+                }
+                return { content };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Document "${title}" (${filename}) is an image but could not be downloaded: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        // PDF: extract text content
+        if (filename.toLowerCase().endsWith(".pdf")) {
+            try {
+                const { buffer } = await client.downloadDocument(documentId);
+                const sizeMB = buffer.byteLength / (1024 * 1024);
+                const pdf = new PDFParse({ data: new Uint8Array(buffer) });
+                const textResult = await pdf.getText();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Document: ${title} (${filename}, ${sizeMB.toFixed(2)} MB, ${textResult.total} pages)\n\n${textResult.text}`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Document "${title}" (${filename}) is a PDF but text extraction failed: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        // Other file types: return metadata only
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        documentId,
+                        filename,
+                        title,
+                        message: "This file type cannot be rendered inline.",
+                        ...document,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/documents.d.ts

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

package/dist/tools/documents.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { registerEndpoints } from "./helpers.js";
+const documentFields = {
+    personid: z.number().describe("Person ID of the document owner (use get_people)"),
+    title: z.string().describe("Document title (max 255 characters)"),
+    notes: z.string().describe("Document body/notes"),
+    public: z.boolean().describe("Whether the document is publicly visible"),
+    active: z.boolean().describe("Whether the document is active"),
+};
+// get_documents and download_document (binary) live in core.
+const specs = [
+    {
+        name: "get_document",
+        description: "Get a single document's metadata by ID. Use download_document to retrieve file contents.",
+        method: "GET",
+        path: "/document",
+        idParam: "documentId",
+        schema: { documentId: z.number().describe("Document ID") },
+    },
+    {
+        name: "create_document",
+        description: "Create a document record (title/notes). Note: the Intervals API does not support uploading file attachments.",
+        method: "POST",
+        path: "/document",
+        schema: {
+            personid: documentFields.personid,
+            title: documentFields.title,
+            notes: documentFields.notes.optional(),
+            public: documentFields.public.optional(),
+            active: documentFields.active.optional(),
+        },
+    },
+    {
+        name: "update_document",
+        description: "Update a document record. Only provide fields you want to change.",
+        method: "PUT",
+        path: "/document",
+        idParam: "documentId",
+        schema: {
+            documentId: z.number().describe("Document ID to update"),
+            personid: documentFields.personid.optional(),
+            title: documentFields.title.optional(),
+            notes: documentFields.notes.optional(),
+            public: documentFields.public.optional(),
+            active: documentFields.active.optional(),
+        },
+    },
+];
+export function registerDocumentTools(server, client) {
+    registerEndpoints(server, client, specs);
+}

package/dist/tools/helpers.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { IntervalsClient, NotificationOptions } from "../client.js";
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Person/owner/assignee style fields accept one ID or a comma-delimited list. */
+export declare const idOrList: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+export declare const limitParam: z.ZodOptional<z.ZodNumber>;
+export declare const offsetParam: z.ZodOptional<z.ZodNumber>;
+/**
+ * Notification controls appended to every write tool (POST/PUT/DELETE).
+ * Both default to off: no header is sent, so the API sends no emails.
+ */
+export declare const notificationShape: {
+    send_notifications: z.ZodOptional<z.ZodBoolean>;
+    disable_action_notes: z.ZodOptional<z.ZodBoolean>;
+};
+/** Split the notification flags off validated tool args. */
+export declare function splitNotifications<T extends Record<string, unknown>>(args: T & {
+    send_notifications?: boolean;
+    disable_action_notes?: boolean;
+}): {
+    fields: Omit<T, "send_notifications" | "disable_action_notes">;
+    notify: NotificationOptions;
+};
+type Args = Record<string, unknown>;
+export interface EndpointSpec {
+    name: string;
+    description: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** API collection path without trailing slash, e.g. "/client". */
+    path: string;
+    /**
+     * Name of the schema field holding the record ID. It is placed in the URL
+     * (`/client/12/`) and never sent in the body or query string.
+     */
+    idParam?: string;
+    schema: z.ZodRawShape;
+    /** Extra body fields always sent (e.g. `{ stop: true }`). */
+    fixedBody?: Args;
+    /** Pre-process validated args (e.g. resolve a local task ID to the internal one). */
+    prepare?: (args: Args, client: IntervalsClient) => Promise<Args>;
+}
+export declare function registerEndpoints(server: McpServer, client: IntervalsClient, specs: EndpointSpec[]): void;
+export {};

package/dist/tools/helpers.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+// --- Shared result + schema helpers ---
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Person/owner/assignee style fields accept one ID or a comma-delimited list. */
+export const idOrList = z.union([z.number(), z.string()]);
+export const limitParam = z
+    .number()
+    .optional()
+    .describe("Maximum number of results to return");
+export const offsetParam = z
+    .number()
+    .optional()
+    .describe("Number of results to skip (pagination)");
+/**
+ * Notification controls appended to every write tool (POST/PUT/DELETE).
+ * Both default to off: no header is sent, so the API sends no emails.
+ */
+export const notificationShape = {
+    send_notifications: z
+        .boolean()
+        .optional()
+        .describe("Send email notifications to the people involved. Emails are NOT sent unless this is true."),
+    disable_action_notes: z
+        .boolean()
+        .optional()
+        .describe("Suppress the automatic action notes Intervals adds to tasks/milestones when they change. Action notes are created unless this is true."),
+};
+/** Split the notification flags off validated tool args. */
+export function splitNotifications(args) {
+    const { send_notifications, disable_action_notes, ...fields } = args;
+    return {
+        fields,
+        notify: {
+            sendNotifications: send_notifications,
+            disableActionNotes: disable_action_notes,
+        },
+    };
+}
+export function registerEndpoints(server, client, specs) {
+    for (const spec of specs) {
+        const isWrite = spec.method !== "GET";
+        const shape = isWrite
+            ? { ...spec.schema, ...notificationShape }
+            : spec.schema;
+        server.tool(spec.name, spec.description, shape, {
+            readOnlyHint: !isWrite,
+            destructiveHint: spec.method === "DELETE",
+        }, async (rawArgs) => {
+            const args = spec.prepare
+                ? await spec.prepare(rawArgs, client)
+                : rawArgs;
+            const { fields: withId, notify } = splitNotifications(args);
+            // The record ID goes in the URL only; never leak it into body/query.
+            let path = spec.path;
+            let fields = withId;
+            if (spec.idParam) {
+                const { [spec.idParam]: id, ...rest } = withId;
+                if (id === undefined || id === null) {
+                    throw new Error(`${spec.name}: missing required parameter "${spec.idParam}"`);
+                }
+                path = `${spec.path}/${encodeURIComponent(String(id))}`;
+                fields = rest;
+            }
+            switch (spec.method) {
+                case "GET":
+                    return jsonResult(await client.get(path, fields));
+                case "DELETE":
+                    return jsonResult(await client.delete(path, fields, notify));
+                case "POST":
+                    return jsonResult(await client.post(path, { ...fields, ...spec.fixedBody }, notify));
+                case "PUT":
+                    return jsonResult(await client.put(path, { ...fields, ...spec.fixedBody }, notify));
+            }
+        });
+    }
+}

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

@@ -0,0 +1,16 @@
+import { registerCoreTools } from "./core.js";
+import { registerTaskTools } from "./tasks.js";
+import { registerTimeTools } from "./time.js";
+import { registerProjectTools } from "./projects.js";
+import { registerPeopleTools } from "./people.js";
+import { registerBillingTools } from "./billing.js";
+import { registerDocumentTools } from "./documents.js";
+export function registerTools(server, client) {
+    registerCoreTools(server, client);
+    registerTaskTools(server, client);
+    registerTimeTools(server, client);
+    registerProjectTools(server, client);
+    registerPeopleTools(server, client);
+    registerBillingTools(server, client);
+    registerDocumentTools(server, client);
+}

package/dist/tools/people.d.ts

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