skedo-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Skedo MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# skedo-mcp
+
+MCP (Model Context Protocol) server for Skedo tasks. A thin, PAT-authenticated
+client over the Skedo HTTP API — no business logic lives here; the Skedo API is
+the source of truth.
+
+Works with any MCP client: Claude Code, Cursor, Claude Desktop, etc.
+
+## Tools
+
+- `list_tasks` — list tasks (optional `limit`, `status`, `search`)
+- `get_task` — fetch one task by UUID or public ref (for example `SK-42`)
+- `create_task` — create a task (requires `title`; other fields optional)
+- `update_task` — validated patch of an existing task
+- `add_task_link` — append a labeled URL (for example a PR link) to task notes
+
+`update_task` accepts only these patch keys: `title`, `description`, `notes`,
+`category`, `tracks`, `priority` (`low | normal | high | urgent`), `status`
+(`todo | inprogress | review | done | rejected | canceled`), `deadline`,
+`assignee` (id string, `null`, or object with `id`).
+
+Compatibility alias: `due_date` is accepted and mapped to `deadline`.
+
+## Configuration
+
+Configuration comes exclusively from environment variables set in your MCP
+client config. There is no `.env` auto-loading.
+
+- `SKEDO_API_BASE_URL` (required) — for example `https://skedo.example.com` or `http://localhost:3000`
+- `SKEDO_API_TOKEN` (required) — Personal Access Token from Skedo settings (`/settings/tokens`)
+- `SKEDO_TIMEOUT_MS` (optional) — outbound API timeout, defaults to `10000`
+
+Treat `SKEDO_API_TOKEN` like a secret. Do not commit it or paste it into shared logs.
+
+## Client config
+
+### Claude Code (`.mcp.json` or `~/.claude.json`)
+
+```json
+{
+  "mcpServers": {
+    "skedo": {
+      "command": "npx",
+      "args": ["-y", "skedo-mcp"],
+      "env": {
+        "SKEDO_API_BASE_URL": "https://your-skedo-url",
+        "SKEDO_API_TOKEN": "<your_pat_here>"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Same shape in Cursor's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "skedo": {
+      "command": "npx",
+      "args": ["-y", "skedo-mcp"],
+      "env": {
+        "SKEDO_API_BASE_URL": "https://your-skedo-url",
+        "SKEDO_API_TOKEN": "<your_pat_here>"
+      }
+    }
+  }
+}
+```
+
+No repo checkout is needed — `npx` fetches the published package. The MCP client
+launches and stops the server process automatically.
+
+## Development
+
+```bash
+npm install
+npm run dev        # run from source (tsx), needs SKEDO_API_* env vars
+npm run build      # compile to dist/
+npm test           # build + unit tests + stdio smoke test
+npm run typecheck
+```
+
+To point a local MCP client at your working copy instead of the npm package:
+
+```json
+{
+  "mcpServers": {
+    "skedo": {
+      "command": "node",
+      "args": ["/absolute/path/to/skedo_mcp/dist/server.js"],
+      "env": {
+        "SKEDO_API_BASE_URL": "http://localhost:3000",
+        "SKEDO_API_TOKEN": "<your_pat_here>"
+      }
+    }
+  }
+}
+```
+
+## Publishing
+
+```bash
+npm publish   # prepublishOnly runs build + tests
+```
+
+## See also
+
+- [`skedo-cli`](https://www.npmjs.com/package/skedo-cli) — terminal client for the same API, same PAT auth

package/dist/normalize.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+export const TASK_STATUS_VALUES = [
+    "todo",
+    "inprogress",
+    "review",
+    "done",
+    "rejected",
+    "canceled",
+];
+export const TASK_PRIORITY_VALUES = ["low", "normal", "high", "urgent"];
+export const assigneeObjectSchema = z
+    .object({
+    id: z.string().min(1),
+})
+    .passthrough();
+export const updateTaskPatchSchema = z
+    .object({
+    title: z.string().optional(),
+    description: z.string().nullable().optional(),
+    notes: z.string().nullable().optional(),
+    category: z.string().optional(),
+    tracks: z.array(z.string()).optional(),
+    priority: z.enum(TASK_PRIORITY_VALUES).optional(),
+    status: z.enum(TASK_STATUS_VALUES).optional(),
+    deadline: z.string().nullable().optional(),
+    due_date: z.string().nullable().optional(),
+    assignee: z.union([z.string(), z.null(), assigneeObjectSchema]).optional(),
+})
+    .strict()
+    .refine((value) => Object.keys(value).length > 0, "patch must include at least one supported field");
+// Shape (not a zod object) for registerTool inputSchema. `title` is required;
+// everything else mirrors the update patch and is optional.
+export const createTaskInputSchema = {
+    title: z.string().min(1),
+    description: z.string().nullable().optional(),
+    notes: z.string().nullable().optional(),
+    category: z.string().optional(),
+    tracks: z.array(z.string()).optional(),
+    priority: z.enum(TASK_PRIORITY_VALUES).optional(),
+    status: z.enum(TASK_STATUS_VALUES).optional(),
+    deadline: z.string().nullable().optional(),
+    due_date: z.string().nullable().optional(),
+    assignee: z.union([z.string(), z.null(), assigneeObjectSchema]).optional(),
+};
+export function normalizeTaskPatch(patch) {
+    const normalizedPatch = { ...patch };
+    const normalizationWarnings = [];
+    if ("due_date" in normalizedPatch && "deadline" in normalizedPatch) {
+        normalizationWarnings.push("Both deadline and due_date were provided. Using deadline and ignoring due_date.");
+    }
+    if ("due_date" in normalizedPatch && !("deadline" in normalizedPatch)) {
+        normalizedPatch.deadline = normalizedPatch.due_date;
+    }
+    delete normalizedPatch.due_date;
+    const assignee = normalizedPatch.assignee;
+    if (assignee && typeof assignee === "object" && "id" in assignee) {
+        normalizationWarnings.push("Assignee object was normalized to assignee id string.");
+        normalizedPatch.assignee = assignee.id;
+    }
+    return { normalizedPatch, normalizationWarnings };
+}

package/dist/server.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { TASK_STATUS_VALUES, createTaskInputSchema, normalizeTaskPatch, updateTaskPatchSchema, } from "./normalize.js";
+// Configuration comes exclusively from environment variables supplied by the
+// MCP client config (Claude Code, Cursor, ...). No .env auto-loading: this
+// server is installed via npm/npx and has no repo root to resolve files from.
+function getRequiredEnv(name) {
+    const value = process.env[name]?.trim();
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+const apiBaseUrl = getRequiredEnv("SKEDO_API_BASE_URL").replace(/\/+$/, "");
+const apiToken = getRequiredEnv("SKEDO_API_TOKEN");
+const timeoutMs = Number(process.env.SKEDO_TIMEOUT_MS ?? "10000");
+if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("SKEDO_TIMEOUT_MS must be a positive number");
+}
+const server = new McpServer({
+    name: "skedo-mcp",
+    version: "0.1.0",
+});
+function toToolResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+        structuredContent: payload,
+    };
+}
+function toErrorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+    };
+}
+async function skedoRequest(path, init = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`${apiBaseUrl}${path}`, {
+            ...init,
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiToken}`,
+                ...(init.headers ?? {}),
+            },
+            signal: controller.signal,
+        });
+        const raw = await response.text();
+        let json;
+        try {
+            json = raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            json = { raw };
+        }
+        if (!response.ok) {
+            const message = typeof json?.error === "string"
+                ? json.error
+                : `Skedo API request failed (${response.status})`;
+            throw new Error(message);
+        }
+        return json;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Skedo API request timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function fetchTask(idOrRef) {
+    const payload = await skedoRequest(`/api/tasks/${encodeURIComponent(idOrRef)}`);
+    if (!payload?.task) {
+        throw new Error("Skedo API returned no task payload");
+    }
+    return payload.task;
+}
+server.registerTool("list_tasks", {
+    title: "List tasks",
+    description: "List tasks from Skedo.",
+    inputSchema: {
+        limit: z.number().int().min(1).max(100).optional(),
+        status: z.enum(TASK_STATUS_VALUES).optional(),
+        search: z.string().min(1).optional(),
+    },
+}, async ({ limit, status, search }) => {
+    try {
+        const payload = await skedoRequest("/api/tasks");
+        const allTasks = Array.isArray(payload?.tasks) ? payload.tasks : [];
+        const normalizedSearch = search?.toLowerCase().trim();
+        const filtered = allTasks.filter((task) => {
+            if (status && task?.status !== status) {
+                return false;
+            }
+            if (!normalizedSearch) {
+                return true;
+            }
+            const title = String(task?.title ?? "").toLowerCase();
+            const description = String(task?.description ?? "").toLowerCase();
+            const notes = String(task?.notes ?? "").toLowerCase();
+            const ref = String(task?.public_ref ?? "").toLowerCase();
+            return (title.includes(normalizedSearch) ||
+                description.includes(normalizedSearch) ||
+                notes.includes(normalizedSearch) ||
+                ref.includes(normalizedSearch));
+        });
+        const finalTasks = typeof limit === "number" && Number.isInteger(limit)
+            ? filtered.slice(0, limit)
+            : filtered;
+        return toToolResult({
+            count: finalTasks.length,
+            items: finalTasks,
+        });
+    }
+    catch (error) {
+        return toErrorResult(error);
+    }
+});
+server.registerTool("get_task", {
+    title: "Get task",
+    description: "Get one task by UUID or public ref (for example SK-42).",
+    inputSchema: {
+        idOrRef: z.string().min(1),
+    },
+}, async ({ idOrRef }) => {
+    try {
+        const task = await fetchTask(idOrRef);
+        return toToolResult({ task });
+    }
+    catch (error) {
+        return toErrorResult(error);
+    }
+});
+server.registerTool("create_task", {
+    title: "Create task",
+    description: "Create a new task in Skedo. Required: title. Optional: description, notes, category (defaults to 'none'), tracks, priority (defaults to normal), status (defaults to todo). New tasks land at the top of their status column. Compatibility alias: due_date (mapped to deadline). Assignee can be an id string ('owner-<profileId>' or an employee id), null, or an object with id.",
+    inputSchema: createTaskInputSchema,
+}, async (args) => {
+    try {
+        // Reuse the update normalizer for the due_date->deadline alias and the
+        // assignee object->id shape so create and update behave identically.
+        const { normalizedPatch, normalizationWarnings } = normalizeTaskPatch(args);
+        if (!("category" in normalizedPatch)) {
+            normalizedPatch.category = "none";
+        }
+        const payload = await skedoRequest("/api/tasks", {
+            method: "POST",
+            body: JSON.stringify(normalizedPatch),
+        });
+        return toToolResult({
+            ...payload,
+            created: normalizedPatch,
+            normalizationWarnings,
+        });
+    }
+    catch (error) {
+        return toErrorResult(error);
+    }
+});
+server.registerTool("update_task", {
+    title: "Update task",
+    description: "Update a task by UUID or public ref. Supported patch fields: title, description, notes, category, tracks, priority, status, deadline, assignee. Compatibility alias: due_date (mapped to deadline). Assignee can be id string, null, or object with id.",
+    inputSchema: {
+        idOrRef: z.string().min(1),
+        patch: updateTaskPatchSchema,
+    },
+}, async ({ idOrRef, patch }) => {
+    try {
+        const { normalizedPatch, normalizationWarnings } = normalizeTaskPatch(patch);
+        const payload = await skedoRequest(`/api/tasks/${encodeURIComponent(idOrRef)}`, {
+            method: "PUT",
+            body: JSON.stringify(normalizedPatch),
+        });
+        return toToolResult({
+            ...payload,
+            patchApplied: normalizedPatch,
+            normalizationWarnings,
+        });
+    }
+    catch (error) {
+        return toErrorResult(error);
+    }
+});
+server.registerTool("add_task_link", {
+    title: "Add task link",
+    description: "Append a labeled URL to task notes, useful for linking PRs (for example GitHub PR URL).",
+    inputSchema: {
+        idOrRef: z.string().min(1),
+        url: z.string().url(),
+        label: z.string().min(1).optional(),
+    },
+}, async ({ idOrRef, url, label }) => {
+    try {
+        const task = await fetchTask(idOrRef);
+        const effectiveLabel = label?.trim() || "Link";
+        const existingNotes = typeof task.notes === "string" ? task.notes.trim() : "";
+        const line = `${effectiveLabel}: ${url}`;
+        if (existingNotes.includes(url)) {
+            return toToolResult({
+                ok: true,
+                skipped: true,
+                reason: "URL already present in task notes",
+                idOrRef,
+                task,
+            });
+        }
+        const notes = existingNotes ? `${existingNotes}\n${line}` : line;
+        const payload = await skedoRequest(`/api/tasks/${encodeURIComponent(idOrRef)}`, {
+            method: "PUT",
+            body: JSON.stringify({ notes }),
+        });
+        return toToolResult({
+            ok: true,
+            idOrRef,
+            appendedLine: line,
+            task: payload?.task ?? null,
+        });
+    }
+    catch (error) {
+        return toErrorResult(error);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "skedo-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP server for Skedo tasks. Thin, PAT-authenticated client over the Skedo API.",
+  "type": "module",
+  "bin": {
+    "skedo-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "skedo",
+    "mcp",
+    "model-context-protocol",
+    "tasks",
+    "kanban"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx src/server.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/server.js",
+    "test": "npm run build && vitest run",
+    "prepack": "node -e \"const fs=require('fs'); if(!fs.existsSync('README.md')){console.error('README.md missing; npm would publish without a readme on the registry'); process.exit(1)}\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}