mcp-intervals 1.5.0 → 1.6.0

package/dist/tools/tasks.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { idOrList, limitParam, offsetParam, registerEndpoints, } from "./helpers.js";
+const localTaskId = z
+    .number()
+    .describe("The local task ID (as shown in the Intervals web UI)");
+// Resolve the local task ID shown in the UI to the internal API ID.
+const resolveLocalTask = (field, target) => async (args, client) => {
+    const { [field]: localId, ...rest } = args;
+    // localId must be required in the tool schema; without it the request would
+    // hit a URL with no task id.
+    if (localId === undefined)
+        return rest;
+    return { ...rest, [target]: await client.resolveTaskId(Number(localId)) };
+};
+const taskFields = {
+    projectid: z.number().describe("Project ID the task belongs to (use get_projects)"),
+    moduleid: z.number().describe("Module ID the task belongs to (use get_project_modules)"),
+    title: z.string().describe("Task title"),
+    statusid: z.number().describe("Status ID (use get_task_statuses)"),
+    priorityid: z.number().describe("Priority ID (use get_task_priorities)"),
+    ownerid: idOrList.describe("Person ID of the task owner, or comma-delimited list of IDs (e.g. '22,334') (use get_people)"),
+    dateopen: z.string().describe("Date the task was opened (YYYY-MM-DD)"),
+    milestoneid: z.number().describe("Milestone ID to associate the task with (use get_milestones)"),
+    summary: z.string().describe("Task description/summary (HTML accepted)"),
+    assigneeid: idOrList.describe("Person ID to assign the task to, or comma-delimited list of IDs"),
+    followerid: idOrList.describe("Person ID to add as a follower, or comma-delimited list of IDs"),
+    estimate: z.number().describe("Estimated hours to complete"),
+    datedue: z.string().describe("Due date (YYYY-MM-DD)"),
+    dateclosed: z.string().describe("Date closed (YYYY-MM-DD)"),
+};
+const filterFields = {
+    personid: z.number().describe("Person ID to save the filter for"),
+    title: z.string().describe("Filter name (max 255 characters)"),
+    params: z.string().describe("Serialized filter parameters string"),
+    date: z.string().describe("Filter date"),
+};
+const specs = [
+    // --- Tasks ---
+    {
+        name: "get_tasks",
+        description: "List tasks with optional filters. Filter by project, module, milestone, assignee, status, or priority. Each ID filter accepts one ID or a comma-delimited list. To filter open vs. closed tasks use statusid (IDs from get_task_statuses).",
+        method: "GET",
+        path: "/task",
+        schema: {
+            projectid: idOrList.optional().describe("Project ID(s)"),
+            moduleid: idOrList.optional().describe("Module ID(s)"),
+            milestoneid: idOrList.optional().describe("Milestone ID(s)"),
+            assigneeid: idOrList.optional().describe("Assignee person ID(s)"),
+            statusid: idOrList.optional().describe("Status ID(s) (use get_task_statuses)"),
+            priorityid: idOrList.optional().describe("Priority ID(s) (use get_task_priorities)"),
+            limit: limitParam,
+            offset: offsetParam,
+        },
+    },
+    {
+        name: "create_task",
+        description: "Create a new task in a project. Requires project, module, title, status, priority, owner, and open date. Emails are not sent unless send_notifications is true.",
+        method: "POST",
+        path: "/task",
+        schema: {
+            projectid: taskFields.projectid,
+            moduleid: taskFields.moduleid,
+            title: taskFields.title,
+            statusid: taskFields.statusid,
+            priorityid: taskFields.priorityid,
+            ownerid: taskFields.ownerid,
+            dateopen: taskFields.dateopen,
+            milestoneid: taskFields.milestoneid.optional(),
+            summary: taskFields.summary.optional(),
+            assigneeid: taskFields.assigneeid.optional(),
+            followerid: taskFields.followerid.optional(),
+            estimate: taskFields.estimate.optional(),
+            datedue: taskFields.datedue.optional(),
+            dateclosed: taskFields.dateclosed.optional(),
+        },
+    },
+    {
+        name: "delete_task",
+        description: "Delete a task by its local ID (as shown in the Intervals web UI). Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/task",
+        idParam: "id",
+        schema: { taskId: localTaskId },
+        prepare: resolveLocalTask("taskId", "id"),
+    },
+    // --- Task notes (get_task_notes / add_task_note live in core) ---
+    {
+        name: "update_task_note",
+        description: "Update a task note by note ID (Administrator only). Only provide fields you want to change.",
+        method: "PUT",
+        path: "/tasknote",
+        idParam: "taskNoteId",
+        schema: {
+            taskNoteId: z.number().describe("Task note ID to update"),
+            note: z.string().optional().describe("Note body (HTML supported)"),
+            public: z.boolean().optional().describe("Whether the note is publicly visible"),
+        },
+    },
+    {
+        name: "delete_task_note",
+        description: "Delete a task note by note ID (Administrator only). Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/tasknote",
+        idParam: "taskNoteId",
+        schema: { taskNoteId: z.number().describe("Task note ID to delete") },
+    },
+    // --- Saved task list filters ---
+    {
+        name: "get_task_filters",
+        description: "List saved task list filters.",
+        method: "GET",
+        path: "/tasklistfilter",
+        schema: { limit: limitParam, offset: offsetParam },
+    },
+    {
+        name: "get_task_filter",
+        description: "Get a single saved task list filter by ID.",
+        method: "GET",
+        path: "/tasklistfilter",
+        idParam: "taskFilterId",
+        schema: { taskFilterId: z.number().describe("Task filter ID") },
+    },
+    {
+        name: "create_task_filter",
+        description: "Save a new task list filter.",
+        method: "POST",
+        path: "/tasklistfilter",
+        schema: {
+            ...filterFields,
+            subfilterid: z.number().optional().describe("Sub-filter ID"),
+            shared: z.boolean().optional().describe("Whether the filter is shared"),
+            scheduled: z.boolean().optional().describe("Whether the filter is scheduled"),
+        },
+    },
+    {
+        name: "update_task_filter",
+        description: "Update a saved task list filter. Only provide fields you want to change.",
+        method: "PUT",
+        path: "/tasklistfilter",
+        idParam: "taskFilterId",
+        schema: {
+            taskFilterId: z.number().describe("Task filter ID to update"),
+            personid: filterFields.personid.optional(),
+            title: filterFields.title.optional(),
+            params: filterFields.params.optional(),
+            date: filterFields.date.optional(),
+            subfilterid: z.number().optional().describe("Sub-filter ID"),
+            shared: z.boolean().optional().describe("Whether the filter is shared"),
+            scheduled: z.boolean().optional().describe("Whether the filter is scheduled"),
+        },
+    },
+    // --- Lookups ---
+    {
+        name: "get_task_statuses",
+        description: "List all task statuses with their IDs. Use these IDs when creating, updating or filtering tasks.",
+        method: "GET",
+        path: "/taskstatus",
+        schema: {},
+    },
+    {
+        name: "get_task_priorities",
+        description: "List all task priorities with their IDs. Use these IDs when creating, updating or filtering tasks.",
+        method: "GET",
+        path: "/taskpriority",
+        schema: {},
+    },
+];
+export function registerTaskTools(server, client) {
+    registerEndpoints(server, client, specs);
+}
+export { localTaskId, resolveLocalTask };

package/dist/tools/time.d.ts

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

package/dist/tools/time.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { registerEndpoints } from "./helpers.js";
+import { localTaskId, resolveLocalTask } from "./tasks.js";
+const timeFields = {
+    worktypeid: z.number().describe("Work type ID (use get_worktypes)"),
+    personid: z.number().describe("Person ID (use get_me or get_people)"),
+    date: z.string().describe("Date of the work (YYYY-MM-DD)"),
+    time: z.number().describe("Hours worked in decimal (e.g. 1.5 for 1h 30m)"),
+    billable: z.boolean().describe("Whether the time is billable"),
+    projectid: z.number().describe("Project ID to associate the time with"),
+    moduleid: z.number().describe("Module ID to associate the time with (use get_project_modules)"),
+    description: z.string().describe("Description of the work performed"),
+};
+const specs = [
+    // --- Timers ---
+    {
+        name: "get_timers",
+        description: "List all active timers for the currently authenticated user.",
+        method: "GET",
+        path: "/timer",
+        schema: {},
+    },
+    {
+        name: "start_timer",
+        description: "Start a timer for a person, optionally on a task. Use get_me to get the current user's person ID.",
+        method: "POST",
+        path: "/timer",
+        schema: {
+            personid: z.number().describe("Person ID to start the timer for (use get_me or get_people)"),
+            taskId: localTaskId.optional(),
+        },
+        prepare: resolveLocalTask("taskId", "taskid"),
+    },
+    {
+        name: "stop_timer",
+        description: "Stop a running timer by its timer ID (use get_timers).",
+        method: "PUT",
+        path: "/timer",
+        idParam: "timerId",
+        schema: { timerId: z.number().describe("Timer ID to stop") },
+        fixedBody: { stop: true },
+    },
+    // --- Time entries (add_time_entry / get_time_entries live in core) ---
+    {
+        name: "update_time_entry",
+        description: "Update an existing time entry. Only provide fields you want to change.",
+        method: "PUT",
+        path: "/time",
+        idParam: "timeEntryId",
+        schema: {
+            timeEntryId: z.number().describe("Time entry ID to update"),
+            worktypeid: timeFields.worktypeid.optional(),
+            personid: timeFields.personid.optional(),
+            date: timeFields.date.optional(),
+            time: timeFields.time.optional(),
+            billable: timeFields.billable.optional(),
+            projectid: timeFields.projectid.optional(),
+            moduleid: timeFields.moduleid.optional(),
+            taskId: localTaskId.optional(),
+            description: timeFields.description.optional(),
+        },
+        prepare: resolveLocalTask("taskId", "taskid"),
+    },
+    {
+        name: "delete_time_entry",
+        description: "Delete a time entry by ID. Permanently deletes; cannot be undone.",
+        method: "DELETE",
+        path: "/time",
+        idParam: "timeEntryId",
+        schema: { timeEntryId: z.number().describe("Time entry ID to delete") },
+    },
+    // --- Work types ---
+    {
+        name: "get_worktypes",
+        description: "List all available work types with their IDs. Use these IDs when adding time entries.",
+        method: "GET",
+        path: "/worktype",
+        schema: {},
+    },
+    // --- Expenses ---
+    {
+        name: "get_expenses",
+        description: "List expense entries, optionally filtered by project or date range.",
+        method: "GET",
+        path: "/expense",
+        schema: {
+            projectid: z.number().optional().describe("Filter by project ID"),
+            datebegin: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+            dateend: z.string().optional().describe("End date (YYYY-MM-DD)"),
+        },
+    },
+    {
+        name: "create_expense",
+        description: "Create an expense entry for a project. Requires project, date, expense amount, and fee amount.",
+        method: "POST",
+        path: "/expense",
+        schema: {
+            projectid: z.number().describe("Project ID (use get_projects)"),
+            date: z.string().describe("Expense date (YYYY-MM-DD)"),
+            expense: z.number().describe("Expense amount"),
+            fee: z.number().describe("Fee amount"),
+            personid: z.number().optional().describe("Person ID (defaults to the authenticated user)"),
+            note: z.string().optional().describe("Expense note (max 255 characters)"),
+        },
+    },
+];
+export function registerTimeTools(server, client) {
+    registerEndpoints(server, client, specs);
+}

package/dist/tools.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { PDFParse } from "pdf-parse";
 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
 export function registerTools(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).", {
@@ -252,6 +256,17 @@ export function registerTools(server, client) {
         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") {
@@ -262,10 +277,35 @@ export function registerTools(server, client) {
         }
         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 = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-intervals",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MCP server for Intervals task management",
   "type": "module",
   "main": "dist/index.js",