@knotsystems/task-overflow-mcp 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# task-overflow-mcp
+
+An MCP (Model Context Protocol) server for **Claude Code** that connects to the **Task Overflow** Mac app. Use Claude to list projects, manage tasks, tags, and subgroups through natural language.
+
+## Prerequisites
+
+- **Task Overflow** Mac app installed and running
+- **Node.js** installed (v18+)
+
+## Installation
+
+Install globally via npm:
+
+```bash
+npm install -g task-overflow-mcp
+```
+
+Or for local development, install from the checked-out repository:
+
+```bash
+cd task-overflow-mcp
+npm install -g .
+```
+
+## Configuration
+
+Add the server to Claude Code with the MCP add command. You must set `TASK_OVERFLOW_TOKEN` so the server can authenticate with the Task Overflow app.
+
+```bash
+claude mcp add task-overflow-mcp --command "task-overflow-mcp" --env "TASK_OVERFLOW_TOKEN=your_token_here"
+```
+
+Or configure via your Claude Code MCP settings (e.g. `~/.claude/claude_mcp_settings.json` or the equivalent in your setup) with the command and environment variable.
+
+### Where to find the token
+
+In the **Task Overflow** app, open **Settings** (⌘,) and copy the API token shown there. Use that value for `TASK_OVERFLOW_TOKEN`.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects |
+| `get_project_tasks` | Get all tasks for a project |
+| `get_project_subgroups` | Get all subgroups for a project |
+| `get_project_tags` | Get all tags for a project |
+| `get_task` | Get a single task by ID |
+| `create_task` | Create a new task |
+| `update_task` | Update a task |
+| `complete_task` | Mark a task as complete |
+| `add_tag_to_task` | Add a tag to a task |
+| `remove_tag_from_task` | Remove a tag from a task |
+
+## How the API works
+
+The MCP server talks to Task Overflow over **local HTTP on port 8491**. All requests use **Bearer token** authentication with your `TASK_OVERFLOW_TOKEN`. The app exposes a REST-style API that the server calls when you use the tools from Claude.
+
+## Note
+
+**The Task Overflow app must be running** for the MCP server to work. If the app is quit or not listening on port 8491, tool calls will fail.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@knotsystems/task-overflow-mcp",
+  "version": "1.0.0",
+  "description": "An MCP server for the Task Overflow Mac app",
+  "author": "Don Parkinson",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "task-overflow",
+    "claude"
+  ],
+  "type": "module",
+  "bin": {
+    "task-overflow-mcp": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const TASK_OVERFLOW_TOKEN = process.env.TASK_OVERFLOW_TOKEN;
+if (!TASK_OVERFLOW_TOKEN) {
+  console.error("task-overflow-mcp: TASK_OVERFLOW_TOKEN is required");
+  process.exit(1);
+}
+
+const BASE_URL = "http://localhost:8491";
+
+async function apiCall(method, path, body) {
+  const url = BASE_URL + path;
+  const options = {
+    method,
+    headers: {
+      Authorization: `Bearer ${TASK_OVERFLOW_TOKEN}`,
+      "Content-Type": "application/json",
+    },
+  };
+  if (body !== undefined) {
+    options.body = JSON.stringify(body);
+  }
+  const response = await fetch(url, options);
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`API ${method} ${path}: ${response.status} ${response.statusText} - ${text}`);
+  }
+  return response.json();
+}
+
+const server = new Server(
+  {
+    name: "task-overflow",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+const TOOLS = [
+  {
+    name: "list_projects",
+    description: "List all projects",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "get_project_tasks",
+    description: "Get all tasks for a project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string", description: "Project ID" },
+      },
+      required: ["projectId"],
+    },
+  },
+  {
+    name: "get_project_subgroups",
+    description: "Get all subgroups for a project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string", description: "Project ID" },
+      },
+      required: ["projectId"],
+    },
+  },
+  {
+    name: "get_project_tags",
+    description: "Get all tags for a project",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string", description: "Project ID" },
+      },
+      required: ["projectId"],
+    },
+  },
+  {
+    name: "get_task",
+    description: "Get a single task by ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task ID" },
+      },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "create_task",
+    description: "Create a new task",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string", description: "Project ID" },
+        name: { type: "string", description: "Task name" },
+        taskDescription: { type: "string", description: "Task description" },
+        priority: { type: "number", description: "Priority" },
+        status: { type: "string", description: "Status" },
+        subgroupId: { type: "string", description: "Subgroup ID" },
+      },
+      required: ["projectId", "name"],
+    },
+  },
+  {
+    name: "update_task",
+    description: "Update a task",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task ID" },
+        name: { type: "string", description: "Task name" },
+        taskDescription: { type: "string", description: "Task description" },
+        priority: { type: "number", description: "Priority" },
+        status: { type: "string", description: "Status" },
+        subgroupId: { type: "string", description: "Subgroup ID" },
+      },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "complete_task",
+    description: "Mark a task as complete",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task ID" },
+      },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "add_tag_to_task",
+    description: "Add a tag to a task",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task ID" },
+        tagId: { type: "string", description: "Tag ID" },
+      },
+      required: ["taskId", "tagId"],
+    },
+  },
+  {
+    name: "remove_tag_from_task",
+    description: "Remove a tag from a task",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task ID" },
+        tagId: { type: "string", description: "Tag ID" },
+      },
+      required: ["taskId", "tagId"],
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  function success(result) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  }
+
+  function error(message) {
+    return {
+      content: [{ type: "text", text: message }],
+      isError: true,
+    };
+  }
+
+  try {
+    switch (name) {
+      case "list_projects": {
+        const result = await apiCall("GET", "/projects");
+        return success(result);
+      }
+      case "get_project_tasks": {
+        const { projectId } = args;
+        if (!projectId) return error("Missing required argument: projectId");
+        const result = await apiCall("GET", `/projects/${encodeURIComponent(projectId)}/tasks`);
+        return success(result);
+      }
+      case "get_project_subgroups": {
+        const { projectId } = args;
+        if (!projectId) return error("Missing required argument: projectId");
+        const result = await apiCall("GET", `/projects/${encodeURIComponent(projectId)}/subgroups`);
+        return success(result);
+      }
+      case "get_project_tags": {
+        const { projectId } = args;
+        if (!projectId) return error("Missing required argument: projectId");
+        const result = await apiCall("GET", `/projects/${encodeURIComponent(projectId)}/tags`);
+        return success(result);
+      }
+      case "get_task": {
+        const { taskId } = args;
+        if (!taskId) return error("Missing required argument: taskId");
+        const result = await apiCall("GET", `/tasks/${encodeURIComponent(taskId)}`);
+        return success(result);
+      }
+      case "create_task": {
+        if (!args.projectId || !args.name) return error("Missing required arguments: projectId, name");
+        const body = {
+          name: args.name,
+          ...(args.taskDescription != null && { taskDescription: args.taskDescription }),
+          ...(args.priority != null && { priority: args.priority }),
+          ...(args.status != null && { status: args.status }),
+          ...(args.subgroupId != null && { subgroupId: args.subgroupId }),
+        };
+        const result = await apiCall("POST", `/projects/${encodeURIComponent(args.projectId)}/tasks`, body);
+        return success(result);
+      }
+      case "update_task": {
+        const { taskId, ...rest } = args;
+        if (!taskId) return error("Missing required argument: taskId");
+        const body = {
+          ...(rest.name != null && { name: rest.name }),
+          ...(rest.taskDescription != null && { taskDescription: rest.taskDescription }),
+          ...(rest.priority != null && { priority: rest.priority }),
+          ...(rest.status != null && { status: rest.status }),
+          ...(rest.subgroupId != null && { subgroupId: rest.subgroupId }),
+        };
+        const result = await apiCall("PUT", `/tasks/${encodeURIComponent(taskId)}`, body);
+        return success(result);
+      }
+      case "complete_task": {
+        const { taskId } = args;
+        if (!taskId) return error("Missing required argument: taskId");
+        const result = await apiCall("POST", `/tasks/${encodeURIComponent(taskId)}/complete`);
+        return success(result);
+      }
+      case "add_tag_to_task": {
+        const { taskId, tagId } = args;
+        if (!taskId || !tagId) return error("Missing required arguments: taskId, tagId");
+        const result = await apiCall("POST", `/tasks/${encodeURIComponent(taskId)}/tags/${encodeURIComponent(tagId)}`);
+        return success(result);
+      }
+      case "remove_tag_from_task": {
+        const { taskId, tagId } = args;
+        if (!taskId || !tagId) return error("Missing required arguments: taskId, tagId");
+        const result = await apiCall("DELETE", `/tasks/${encodeURIComponent(taskId)}/tags/${encodeURIComponent(tagId)}`);
+        return success(result);
+      }
+      default:
+        return error("Unknown tool");
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return error(message);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);