mcp-intervals 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+export interface IntervalsRequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: Record<string, unknown>;
+    params?: Record<string, string | number | boolean>;
+}
+export declare class IntervalsClient {
+    private baseUrl;
+    private authHeader;
+    constructor(apiToken: string);
+    private request;
+    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>>;
+    getProject(id: number): Promise<Record<string, unknown>>;
+    getMilestone(id: number): Promise<Record<string, unknown>>;
+    getTaskStatuses(): Promise<Record<string, unknown>>;
+    getTaskPriorities(): Promise<Record<string, unknown>>;
+}

package/dist/client.js

@@ -0,0 +1,85 @@
+export class IntervalsClient {
+    baseUrl = "https://api.myintervals.com";
+    authHeader;
+    constructor(apiToken) {
+        this.authHeader =
+            "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 headers = {
+            Authorization: this.authHeader,
+            Accept: "application/json",
+        };
+        const fetchOptions = { method, headers };
+        if (body) {
+            headers["Content-Type"] = "application/json";
+            fetchOptions.body = JSON.stringify(body);
+        }
+        const response = await fetch(url, fetchOptions);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Intervals API error ${response.status}: ${text}`);
+        }
+        return response.json();
+    }
+    // --- Task ---
+    async getTask(id) {
+        const data = await this.request(`/task/${id}/`);
+        return data;
+    }
+    async getTaskByLocalId(localId) {
+        const data = await this.request(`/task/`, { params: { localid: localId } });
+        if (!data.task || data.task.length === 0) {
+            throw new Error(`No task found with local ID ${localId}`);
+        }
+        return data.task[0];
+    }
+    async resolveTaskId(localId) {
+        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 });
+        return data;
+    }
+    // --- Task Notes ---
+    async getTaskNotes(taskId) {
+        const data = await this.request(`/tasknote/`, { params: { taskid: taskId } });
+        return data;
+    }
+    async addTaskNote(taskId, note, isPublic = true) {
+        const data = await this.request(`/tasknote/`, {
+            method: "POST",
+            body: { taskid: taskId, note, public: isPublic },
+        });
+        return data;
+    }
+    // --- Project ---
+    async getProject(id) {
+        const data = await this.request(`/project/${id}/`);
+        return data;
+    }
+    // --- Milestone ---
+    async getMilestone(id) {
+        const data = await this.request(`/milestone/${id}/`);
+        return data;
+    }
+    // --- Resources (statuses & priorities) ---
+    async getTaskStatuses() {
+        const data = await this.request(`/taskstatus/`);
+        return data;
+    }
+    async getTaskPriorities() {
+        const data = await this.request(`/taskpriority/`);
+        return data;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { IntervalsClient } from "./client.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+const API_TOKEN = process.env.INTERVALS_API_TOKEN;
+if (!API_TOKEN) {
+    console.error("Error: INTERVALS_API_TOKEN environment variable is required.");
+    process.exit(1);
+}
+const client = new IntervalsClient(API_TOKEN);
+const server = new McpServer({
+    name: "mcp-intervals",
+    version: "1.0.0",
+});
+registerTools(server, client);
+registerResources(server, client);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/resources.d.ts

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

package/dist/resources.js

@@ -0,0 +1,34 @@
+export function registerResources(server, client) {
+    // --- Task Statuses ---
+    server.resource("task-statuses", "intervals://statuses", {
+        description: "List of all task statuses with their IDs. Use these IDs when updating a task's status.",
+        mimeType: "application/json",
+    }, async () => {
+        const data = await client.getTaskStatuses();
+        return {
+            contents: [
+                {
+                    uri: "intervals://statuses",
+                    mimeType: "application/json",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    });
+    // --- Task Priorities ---
+    server.resource("task-priorities", "intervals://priorities", {
+        description: "List of all task priorities with their IDs. Use these IDs when updating a task's priority.",
+        mimeType: "application/json",
+    }, async () => {
+        const data = await client.getTaskPriorities();
+        return {
+            contents: [
+                {
+                    uri: "intervals://priorities",
+                    mimeType: "application/json",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools.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.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { parseTaskIdFromUrl } 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).", {
+        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);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- update_task ---
+    server.tool("update_task", "Update fields on an Intervals task (status, assignee, priority, title, due date, owner).", {
+        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: z
+            .number()
+            .optional()
+            .describe("New assignee person ID"),
+        priorityid: z
+            .number()
+            .optional()
+            .describe("New priority ID (use intervals://priorities resource for valid IDs)"),
+        title: z.string().optional().describe("New task title"),
+        datedue: z
+            .string()
+            .optional()
+            .describe("New due date in YYYY-MM-DD format"),
+        ownerid: z
+            .number()
+            .optional()
+            .describe("New owner person ID"),
+    }, async ({ taskId, ...fields }) => {
+        // 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);
+        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.", {
+        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)"),
+        isPublic: z
+            .boolean()
+            .default(true)
+            .describe("Whether the note is visible to executive users (defaults to true)"),
+    }, async ({ taskId, note, isPublic }) => {
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.addTaskNote(internalId, note, isPublic);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    });
+    // --- get_task_notes ---
+    server.tool("get_task_notes", "Retrieve all comments/notes on an Intervals task.", {
+        taskId: z
+            .number()
+            .describe("The local task ID (as shown in the Intervals web UI)"),
+    }, async ({ taskId }) => {
+        const internalId = await client.resolveTaskId(taskId);
+        const data = await client.getTaskNotes(internalId);
+        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) },
+            ],
+        };
+    });
+}

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse an Intervals task URL to extract the task ID.
+ * Accepts URLs like: https://<subdomain>.intervalsonline.com/tasks/view/<taskId>
+ * Also accepts a raw numeric string/number as fallback.
+ */
+export declare function parseTaskIdFromUrl(input: string): number;

package/dist/utils.js

@@ -0,0 +1,16 @@
+/**
+ * Parse an Intervals task URL to extract the task ID.
+ * Accepts URLs like: https://<subdomain>.intervalsonline.com/tasks/view/<taskId>
+ * Also accepts a raw numeric string/number as fallback.
+ */
+export function parseTaskIdFromUrl(input) {
+    const match = input.match(/\/tasks\/view\/(\d+)/);
+    if (match) {
+        return parseInt(match[1], 10);
+    }
+    const asNumber = parseInt(input, 10);
+    if (!isNaN(asNumber) && asNumber > 0) {
+        return asNumber;
+    }
+    throw new Error(`Cannot parse task ID from: "${input}". Expected a URL like https://<subdomain>.intervalsonline.com/tasks/view/<id> or a numeric ID.`);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "mcp-intervals",
+  "version": "1.0.0",
+  "description": "MCP server for Intervals task management",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-intervals": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "intervals",
+    "task-management"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/educlopez/mcp-intervals.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}