@taskinger/mcp 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @taskinger/mcp
+
+An MCP server for [Taskinger](https://taskinger.app): work in one workbook —
+its tasks and its notes — from Claude Desktop, Claude Code, Cursor or any
+other MCP client.
+
+Tasks say what to do. Notes are where an assistant writes down what it
+learned, so the next session does not work it out again.
+
+## Setup
+
+Mint a key in the app: **Workbook settings → External API** (Team plan). Give
+it the write scope if the assistant should create and edit things rather than
+only read them.
+
+Claude Code:
+
+```bash
+claude mcp add taskinger -e TASKINGER_API_KEY=zad_… -e TASKINGER_WORKBOOK=… -- npx -y @taskinger/mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`) or Cursor (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "taskinger": {
+      "command": "npx",
+      "args": ["-y", "@taskinger/mcp"],
+      "env": {
+        "TASKINGER_API_KEY": "zad_…",
+        "TASKINGER_WORKBOOK": "the workbook id, as in https://taskinger.app/w/<id>"
+      }
+    }
+  }
+}
+```
+
+| Variable | |
+|---|---|
+| `TASKINGER_API_KEY` | `zad_<keyId>.<secret>`, from Workbook settings → External API |
+| `TASKINGER_WORKBOOK` | the workbook id from its address |
+| `TASKINGER_API_BASE` | optional; defaults to `https://taskinger.app/api` |
+
+## Tools
+
+**Tasks** — `list_tasks`, `get_task`, `create_task`, `update_task`,
+`complete_task`.
+
+**Notes** — `list_notes`, `get_note`, `create_note`, `update_note`. A note is
+written prose; a list is ticked off. A list's lines are edited by name (add,
+tick by line id, remove by line id), so an edit here never overwrites a line
+somebody changed in the app meanwhile.
+
+**Lookups** — `get_workbook` (including the house rules on task intake),
+`list_members`, `list_projects`, `list_labels`.
+
+## Scope
+
+One workbook per server process, named by the environment, so an assistant
+only ever sees and touches what the key was minted for — a key cannot reach
+another workbook. A read-only key gives a read-only assistant. Everything the
+server writes goes through the same API the app's own integrations use, so it
+lands in the activity log, pushes and webhooks like any other change, and the
+workbook's house rules are enforced.
+
+Full API reference: [taskinger.app/openapi.yaml](https://taskinger.app/openapi.yaml).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+/**
+ * Taskinger MCP server: a thin, stdio-speaking wrapper over the task API
+ * (https://taskinger.app/openapi.yaml). One workbook per process, named by
+ * the environment, so an assistant can only ever see and touch what the key
+ * was minted for.
+ *
+ *   TASKINGER_API_KEY   zad_<keyId>.<secret>  (Workbook settings → External API)
+ *   TASKINGER_WORKBOOK  the workbook id, as in https://taskinger.app/w/<id>
+ *   TASKINGER_API_BASE  optional; defaults to https://taskinger.app/api
+ */
+const KEY = process.env.TASKINGER_API_KEY;
+const WS = process.env.TASKINGER_WORKBOOK;
+const BASE = (process.env.TASKINGER_API_BASE ?? 'https://taskinger.app/api').replace(/\/+$/, '');
+if (!KEY || !WS) {
+    console.error('Set TASKINGER_API_KEY and TASKINGER_WORKBOOK. Both come from Workbook settings → External API.');
+    process.exit(1);
+}
+async function call(method, path, body, query) {
+    const url = new URL(`${BASE}/v1/workbooks/${WS}${path}`);
+    for (const [k, v] of Object.entries(query ?? {}))
+        if (v !== undefined && v !== '')
+            url.searchParams.set(k, v);
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${KEY}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'taskinger-mcp/0.1',
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = { error: text };
+    }
+    if (!res.ok) {
+        const message = data?.error ?? `HTTP ${res.status}`;
+        throw new Error(`${message} (HTTP ${res.status})`);
+    }
+    return data;
+}
+const json = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const failure = (error) => ({
+    content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+    isError: true,
+});
+const server = new McpServer({ name: 'taskinger', version: '0.1.0' });
+const statusEnum = z.enum(['todo', 'in_progress', 'awaiting_approval', 'done']);
+const taskFields = {
+    title: z.string().max(200).optional().describe('The task title'),
+    description: z.string().max(20000).optional().describe('Markdown'),
+    priority: z.number().int().min(1).max(4).optional().describe('1 urgent, 2 high, 3 normal, 4 someday'),
+    assigneeUids: z.array(z.string()).optional().describe('Member uids from list_members'),
+    labelIds: z.array(z.string()).max(20).optional().describe('Label ids from list_labels'),
+    projectId: z.string().nullable().optional().describe('A project id from list_projects, or null for the workbook root'),
+    dueDate: z.string().nullable().optional().describe('ISO-8601 date-time, or null to clear'),
+    dueHasTime: z.boolean().optional().describe('Whether dueDate carries a clock time; false means all day'),
+    checklist: z.array(z.string()).max(50).optional().describe('Checklist steps, one string each'),
+};
+server.tool('get_workbook', 'The workbook this server is connected to: its name, type and house rules (required due date, assignee, completion note, sign-off).', {}, async () => {
+    try {
+        return json(await call('GET', ''));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('list_tasks', 'List tasks, most recently updated first. Filter by status (comma-separated: todo, in_progress, awaiting_approval, done), assignee uid, project id (or "root"), or updatedSince (ISO-8601). Up to 200.', {
+    status: z.string().optional(),
+    assignee: z.string().optional(),
+    projectId: z.string().optional(),
+    updatedSince: z.string().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+}, async (args) => {
+    try {
+        return json(await call('GET', '/tasks', undefined, { ...args, limit: args.limit?.toString() }));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('get_task', 'One task by id, with its checklist, dates, assignees and address in the app.', { taskId: z.string() }, async ({ taskId }) => {
+    try {
+        return json(await call('GET', `/tasks/${encodeURIComponent(taskId)}`));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('create_task', 'Create a task. Only the title is required; the workbook may also require a due date or an assignee (see get_workbook).', { ...taskFields, title: z.string().min(1).max(200) }, async (args) => {
+    try {
+        return json(await call('POST', '/tasks', args));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('update_task', 'Change fields of a task. Only the fields given change. Set status to move it; finishing (done or awaiting_approval) may require completionNote.', { taskId: z.string(), ...taskFields, status: statusEnum.optional(), completionNote: z.string().max(2000).nullable().optional() }, async ({ taskId, ...patch }) => {
+    try {
+        return json(await call('PATCH', `/tasks/${encodeURIComponent(taskId)}`, patch));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('complete_task', 'Mark a task done, with an optional note saying what was done (required when the workbook asks for one).', { taskId: z.string(), note: z.string().max(2000).optional() }, async ({ taskId, note }) => {
+    try {
+        return json(await call('POST', `/tasks/${encodeURIComponent(taskId)}/complete`, note === undefined ? {} : { note }));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+/* Notes are where an assistant writes down what it learned, so the next
+ * session does not derive it again: prose (`note`) or a ticked `list`. */
+server.tool('list_notes', 'List notes and lists, most recently updated first. Filter by kind ("note" or "list"), project id (or "root" for the workbook\'s general shelf), or updatedSince (ISO-8601). Up to 200.', {
+    kind: z.enum(['note', 'list']).optional(),
+    projectId: z.string().optional(),
+    updatedSince: z.string().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+}, async (args) => {
+    try {
+        return json(await call('GET', '/notes', undefined, { ...args, limit: args.limit?.toString() }));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('get_note', 'One note by id, with its body or its lines and their ids.', { noteId: z.string() }, async ({ noteId }) => {
+    try {
+        return json(await call('GET', `/notes/${encodeURIComponent(noteId)}`));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('create_note', 'Write a note into the workbook, or into one of its projects — the place to record a decision, a gotcha or a piece of context worth keeping. Use kind "list" with items for something to tick off instead.', {
+    title: z.string().min(1).max(200),
+    body: z.string().max(20000).optional().describe('Markdown. The note itself.'),
+    kind: z.enum(['note', 'list']).optional().describe('Default "note". Fixed at creation.'),
+    items: z.array(z.string().max(120)).max(200).optional().describe('Lines, only on a list'),
+    projectId: z.string().nullable().optional().describe('A project id from list_projects, or null for the workbook\'s general shelf'),
+    pinned: z.boolean().optional(),
+}, async (args) => {
+    try {
+        return json(await call('POST', '/notes', args));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+server.tool('update_note', 'Change a note: its title, body or pinning. On a list, edit lines by name — add new ones, tick them by id, remove them by id — which never overwrites a line somebody else changed meanwhile. Line ids come from get_note.', {
+    noteId: z.string(),
+    title: z.string().min(1).max(200).optional(),
+    body: z.string().max(20000).optional(),
+    pinned: z.boolean().optional(),
+    items: z
+        .object({
+        add: z.array(z.string().max(120)).optional(),
+        done: z.record(z.boolean()).optional().describe('Line id → ticked or not'),
+        remove: z.array(z.string()).optional().describe('Line ids'),
+    })
+        .optional()
+        .describe('Lists only'),
+}, async ({ noteId, ...patch }) => {
+    try {
+        return json(await call('PATCH', `/notes/${encodeURIComponent(noteId)}`, patch));
+    }
+    catch (error) {
+        return failure(error);
+    }
+});
+for (const [name, path, what] of [
+    ['list_members', '/members', 'Members of the workbook, with the uids used for assigning.'],
+    ['list_projects', '/projects', 'Projects of the workbook, with the ids used for filing.'],
+    ['list_labels', '/labels', 'Labels of the workbook, with the ids used on tasks.'],
+]) {
+    server.tool(name, what, {}, async () => {
+        try {
+            return json(await call('GET', path));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@taskinger/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Taskinger: read and write the tasks and notes of one workbook from Claude, Cursor or any MCP client.",
+  "license": "MIT",
+  "author": "Taskinger",
+  "homepage": "https://taskinger.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MegaVmetal/Taskinger.app.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/MegaVmetal/Taskinger.app/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "taskinger",
+    "tasks",
+    "notes",
+    "claude",
+    "cursor"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "taskinger-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}