mcp-intervals 1.3.2 → 1.4.0

package/dist/client.d.ts

@@ -8,6 +8,7 @@ export declare class IntervalsClient {
     private authHeader;
     constructor(apiToken: string);
     private request;
+    private requestBinary;
     getTask(id: number): Promise<Record<string, unknown>>;
     getTaskByLocalId(localId: number): Promise<Record<string, unknown>>;
     resolveTaskId(localId: number): Promise<number>;
@@ -16,6 +17,16 @@ export declare class IntervalsClient {
     addTaskNote(taskId: number, note: string, isPublic?: boolean): 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>>;
+    getDocument(id: number): Promise<Record<string, unknown>>;
+    downloadDocument(id: number): Promise<{
+        buffer: ArrayBuffer;
+        contentType: string;
+    }>;
     getTaskStatuses(): Promise<Record<string, unknown>>;
     getTaskPriorities(): Promise<Record<string, unknown>>;
     getWorkTypes(): Promise<Record<string, unknown>>;

package/dist/client.js

@@ -31,6 +31,27 @@ export class IntervalsClient {
         }
         return response.json();
     }
+    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 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}`);
+        }
+        const buffer = await response.arrayBuffer();
+        const contentType = response.headers.get("content-type") || "application/octet-stream";
+        return { buffer, contentType };
+    }
     // --- Task ---
     async getTask(id) {
         const data = await this.request(`/task/${id}/`);
@@ -73,6 +94,20 @@ export class IntervalsClient {
         const data = await this.request(`/milestone/${id}/`);
         return data;
     }
+    // --- Documents ---
+    async getDocuments(params = {}) {
+        const data = await this.request(`/document/`, {
+            params: params,
+        });
+        return data;
+    }
+    async getDocument(id) {
+        const data = await this.request(`/document/${id}/`);
+        return data;
+    }
+    async downloadDocument(id) {
+        return this.requestBinary(`/document/${id}/download/`);
+    }
     // --- Resources (statuses & priorities) ---
     async getTaskStatuses() {
         const data = await this.request(`/taskstatus/`);

package/dist/tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { parseTaskIdFromUrl } from "./utils.js";
+import { parseTaskIdFromUrl, getMimeTypeFromFilename, isImageMimeType, } from "./utils.js";
 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).", {
@@ -9,11 +9,32 @@ export function registerTools(server, client) {
     }, async ({ task }) => {
         const localId = parseTaskIdFromUrl(task);
         const data = await client.getTaskByLocalId(localId);
-        return {
-            content: [
-                { type: "text", text: JSON.stringify(data, null, 2) },
-            ],
-        };
+        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, due date, owner).", {
@@ -34,7 +55,7 @@ export function registerTools(server, client) {
         summary: z
             .string()
             .optional()
-            .describe("New task description/summary (HTML is accepted)"),
+            .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()
@@ -74,7 +95,7 @@ export function registerTools(server, client) {
         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)"),
+            .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)
@@ -195,4 +216,96 @@ export function registerTools(server, client) {
             ],
         };
     });
+    // --- 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"),
+    }, async ({ taskId, projectId, personId }) => {
+        let internalTaskId;
+        if (taskId) {
+            internalTaskId = await client.resolveTaskId(taskId);
+        }
+        const data = await client.getDocuments({
+            taskid: internalTaskId,
+            projectid: projectId,
+            personid: personId,
+        });
+        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 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 document = docData.document?.[0] ??
+            docData;
+        const filename = document.filename || "unknown";
+        const title = document.title || filename;
+        const imageMimeType = getMimeTypeFromFilename(filename);
+        if (imageMimeType && isImageMimeType(imageMimeType)) {
+            try {
+                const { buffer } = await client.downloadDocument(documentId);
+                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,
+                };
+            }
+        }
+        // Non-image file: 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/utils.d.ts

@@ -4,3 +4,5 @@
  * Also accepts a raw numeric string/number as fallback.
  */
 export declare function parseTaskIdFromUrl(input: string): number;
+export declare function getMimeTypeFromFilename(filename: string): string | null;
+export declare function isImageMimeType(mimeType: string): boolean;

package/dist/utils.js

@@ -14,3 +14,22 @@ export function parseTaskIdFromUrl(input) {
     }
     throw new Error(`Cannot parse task ID from: "${input}". Expected a URL like https://<subdomain>.intervalsonline.com/tasks/view/<id> or a numeric ID.`);
 }
+// --- Image MIME type helpers ---
+const IMAGE_EXTENSIONS = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+};
+const IMAGE_MIME_TYPES = new Set(Object.values(IMAGE_EXTENSIONS));
+export function getMimeTypeFromFilename(filename) {
+    const ext = filename.toLowerCase().match(/\.[^.]+$/)?.[0];
+    return ext ? IMAGE_EXTENSIONS[ext] ?? null : null;
+}
+export function isImageMimeType(mimeType) {
+    return IMAGE_MIME_TYPES.has(mimeType);
+}

package/package.json

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