@delega-dev/mcp 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delega 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,70 @@
+# delega-mcp
+
+MCP server for [Delega](https://delega.dev) — task infrastructure for AI agents.
+
+Connect any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) to your Delega instance and manage tasks, projects, and agents through natural language.
+
+## Install
+
+```bash
+npm install -g delega-mcp
+```
+
+## Configure
+
+Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "delega": {
+      "command": "delega-mcp",
+      "env": {
+        "DELEGA_API_URL": "http://127.0.0.1:18890",
+        "DELEGA_AGENT_KEY": "dlg_your_agent_key_here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DELEGA_API_URL` | `http://127.0.0.1:18890` | Delega API endpoint |
+| `DELEGA_AGENT_KEY` | (none) | Agent API key for authenticated requests |
+
+For the hosted tier, use `https://api.delega.dev` as the URL.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tasks` | List tasks, filter by project, label, due date, completion |
+| `get_task` | Get full task details including subtasks |
+| `create_task` | Create a new task |
+| `update_task` | Update task fields |
+| `complete_task` | Mark a task as completed |
+| `delete_task` | Delete a task permanently |
+| `add_comment` | Add a comment to a task |
+| `list_projects` | List all projects |
+| `get_stats` | Get task statistics |
+| `list_agents` | List registered agents |
+| `register_agent` | Register a new agent (returns API key) |
+
+## Self-Hosted vs Hosted
+
+**Self-hosted (free):** Run your own Delega instance, point `DELEGA_API_URL` at it.
+
+**Hosted:** Use `https://api.delega.dev` — free up to 1,000 tasks/month.
+
+## Links
+
+- [Delega](https://delega.dev) — Main site
+- [GitHub](https://github.com/delega-dev/delega-mcp) — Source code
+- [API Docs](https://delega.dev/docs) — REST API reference
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/delega-client.ts
+var DEFAULT_BASE_URL = "http://127.0.0.1:18890";
+var DelegaClient = class {
+  baseUrl;
+  agentKey;
+  constructor(baseUrl, agentKey) {
+    this.baseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.agentKey = agentKey;
+  }
+  async request(method, path, body, query) {
+    const url = new URL(path, this.baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.agentKey) {
+      headers["X-Agent-Key"] = this.agentKey;
+    }
+    const res = await fetch(url.toString(), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `Delega API error: ${res.status} ${res.statusText}${text ? ` \u2014 ${text}` : ""}`
+      );
+    }
+    if (res.status === 204) {
+      return void 0;
+    }
+    return res.json();
+  }
+  // ── Tasks ──
+  async listTasks(params) {
+    const query = {};
+    if (params.project_id !== void 0) query.project_id = String(params.project_id);
+    if (params.label !== void 0) query.label = params.label;
+    if (params.due !== void 0) query.due = params.due;
+    if (params.completed !== void 0) query.completed = String(params.completed);
+    return this.request("GET", "/api/tasks", void 0, query);
+  }
+  async getTask(taskId) {
+    return this.request("GET", `/api/tasks/${taskId}`);
+  }
+  async createTask(data) {
+    return this.request("POST", "/api/tasks", data);
+  }
+  async updateTask(taskId, data) {
+    return this.request("PUT", `/api/tasks/${taskId}`, data);
+  }
+  async completeTask(taskId) {
+    return this.request("POST", `/api/tasks/${taskId}/complete`);
+  }
+  async deleteTask(taskId) {
+    return this.request("DELETE", `/api/tasks/${taskId}`);
+  }
+  // ── Comments ──
+  async addComment(taskId, data) {
+    return this.request(
+      "POST",
+      `/api/tasks/${taskId}/comments`,
+      data
+    );
+  }
+  // ── Projects ──
+  async listProjects() {
+    return this.request("GET", "/api/projects");
+  }
+  // ── Stats ──
+  async getStats() {
+    return this.request("GET", "/api/stats");
+  }
+  // ── Agents ──
+  async listAgents() {
+    return this.request("GET", "/api/agents");
+  }
+  async registerAgent(data) {
+    return this.request("POST", "/api/agents", data);
+  }
+};
+
+// src/index.ts
+var client = new DelegaClient(
+  process.env.DELEGA_API_URL,
+  process.env.DELEGA_AGENT_KEY
+);
+function formatTask(t) {
+  const lines = [];
+  lines.push(`[#${t.id}] ${t.content}`);
+  if (t.description) lines.push(`  Description: ${t.description}`);
+  if (t.project?.name ?? t.project_name)
+    lines.push(`  Project: ${t.project?.name ?? t.project_name}`);
+  if (t.labels?.length) lines.push(`  Labels: ${t.labels.join(", ")}`);
+  if (t.priority) lines.push(`  Priority: ${t.priority}`);
+  if (t.due_date) lines.push(`  Due: ${t.due_date}`);
+  lines.push(`  Completed: ${t.completed ? "yes" : "no"}`);
+  if (t.subtasks?.length) {
+    lines.push(`  Subtasks:`);
+    for (const s of t.subtasks) {
+      lines.push(`    [#${s.id}] ${s.content} (${s.completed ? "done" : "pending"})`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatProject(p) {
+  return `[#${p.id}] ${p.name}`;
+}
+function formatAgent(a) {
+  const lines = [];
+  lines.push(`[#${a.id}] ${a.name}${a.display_name ? ` (${a.display_name})` : ""}`);
+  if (a.description) lines.push(`  Description: ${a.description}`);
+  if (a.api_key) lines.push(`  API Key: ${a.api_key}`);
+  if (a.permissions?.length) lines.push(`  Permissions: ${a.permissions.join(", ")}`);
+  if (a.active !== void 0) lines.push(`  Active: ${a.active ? "yes" : "no"}`);
+  return lines.join("\n");
+}
+var server = new McpServer({
+  name: "delega-mcp",
+  version: "1.0.0"
+});
+server.tool(
+  "list_tasks",
+  "List tasks from Delega, optionally filtered by project, label, due date, or completion status",
+  {
+    project_id: z.number().int().optional().describe("Filter by project ID"),
+    label: z.string().optional().describe("Filter by label name"),
+    due: z.enum(["today", "upcoming", "overdue"]).optional().describe("Filter by due date category"),
+    completed: z.boolean().optional().describe("Filter by completion status")
+  },
+  async ({ project_id, label, due, completed }) => {
+    try {
+      const tasks = await client.listTasks({ project_id, label, due, completed });
+      if (!tasks.length) {
+        return { content: [{ type: "text", text: "No tasks found." }] };
+      }
+      const text = tasks.map(formatTask).join("\n\n");
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "get_task",
+  "Get full details of a specific task including subtasks",
+  {
+    task_id: z.number().int().describe("The task ID")
+  },
+  async ({ task_id }) => {
+    try {
+      const task = await client.getTask(task_id);
+      return { content: [{ type: "text", text: formatTask(task) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "create_task",
+  "Create a new task in Delega",
+  {
+    content: z.string().describe("Task title / content"),
+    description: z.string().optional().describe("Detailed description"),
+    project_id: z.number().int().optional().describe("Project ID to assign to"),
+    labels: z.array(z.string()).optional().describe("Labels to apply"),
+    priority: z.number().int().min(1).max(4).optional().describe("Priority: 1=normal, 2=medium, 3=high, 4=urgent"),
+    due_date: z.string().optional().describe("Due date in YYYY-MM-DD format")
+  },
+  async (params) => {
+    try {
+      const task = await client.createTask(params);
+      return {
+        content: [{ type: "text", text: `Task created:
+
+${formatTask(task)}` }]
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "update_task",
+  "Update an existing task's fields",
+  {
+    task_id: z.number().int().describe("The task ID to update"),
+    content: z.string().optional().describe("New task title / content"),
+    description: z.string().optional().describe("New description"),
+    labels: z.array(z.string()).optional().describe("New labels"),
+    priority: z.number().int().optional().describe("New priority (1-4)"),
+    due_date: z.string().optional().describe("New due date (YYYY-MM-DD)"),
+    project_id: z.number().int().optional().describe("Move to project ID")
+  },
+  async ({ task_id, ...updates }) => {
+    try {
+      const task = await client.updateTask(task_id, updates);
+      return {
+        content: [{ type: "text", text: `Task updated:
+
+${formatTask(task)}` }]
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "complete_task",
+  "Mark a task as completed",
+  {
+    task_id: z.number().int().describe("The task ID to complete")
+  },
+  async ({ task_id }) => {
+    try {
+      const task = await client.completeTask(task_id);
+      let text = `Task #${task_id} completed.`;
+      if (task?.next_occurrence) {
+        text += `
+Next occurrence: ${task.next_occurrence}`;
+      }
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "delete_task",
+  "Delete a task permanently",
+  {
+    task_id: z.number().int().describe("The task ID to delete")
+  },
+  async ({ task_id }) => {
+    try {
+      await client.deleteTask(task_id);
+      return {
+        content: [{ type: "text", text: `Task #${task_id} deleted.` }]
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "add_comment",
+  "Add a comment to a task",
+  {
+    task_id: z.number().int().describe("The task ID to comment on"),
+    content: z.string().describe("Comment text"),
+    author: z.string().optional().describe("Comment author name")
+  },
+  async ({ task_id, content, author }) => {
+    try {
+      const comment = await client.addComment(task_id, { content, author });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Comment added to task #${task_id}:
+  "${comment.content ?? content}"${comment.author ? ` \u2014 ${comment.author}` : ""}`
+          }
+        ]
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "list_projects",
+  "List all projects in Delega",
+  {},
+  async () => {
+    try {
+      const projects = await client.listProjects();
+      if (!projects.length) {
+        return { content: [{ type: "text", text: "No projects found." }] };
+      }
+      const text = projects.map(formatProject).join("\n");
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "get_stats",
+  "Get task statistics from Delega (totals, completed today, due today, overdue, by project)",
+  {},
+  async () => {
+    try {
+      const stats = await client.getStats();
+      const lines = ["Task Statistics:"];
+      if (stats.total !== void 0) lines.push(`  Total tasks: ${stats.total}`);
+      if (stats.completed_today !== void 0) lines.push(`  Completed today: ${stats.completed_today}`);
+      if (stats.due_today !== void 0) lines.push(`  Due today: ${stats.due_today}`);
+      if (stats.overdue !== void 0) lines.push(`  Overdue: ${stats.overdue}`);
+      if (stats.by_project) {
+        lines.push("  By project:");
+        for (const [name, count] of Object.entries(stats.by_project)) {
+          lines.push(`    ${name}: ${count}`);
+        }
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "list_agents",
+  "List all registered agents in Delega",
+  {},
+  async () => {
+    try {
+      const agents = await client.listAgents();
+      if (!agents.length) {
+        return { content: [{ type: "text", text: "No agents registered." }] };
+      }
+      const text = agents.map(formatAgent).join("\n\n");
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+server.tool(
+  "register_agent",
+  "Register a new agent in Delega. Returns the API key (shown only at creation \u2014 save it!)",
+  {
+    name: z.string().describe("Unique agent name (e.g. 'coordinator', 'researcher')"),
+    display_name: z.string().optional().describe("Human-readable name (e.g. 'Research Bot')"),
+    description: z.string().optional().describe("What this agent does"),
+    permissions: z.array(z.string()).optional().describe("Permission scopes (e.g. ['tasks:read', 'tasks:write'])")
+  },
+  async (params) => {
+    try {
+      const agent = await client.registerAgent(params);
+      return {
+        content: [{ type: "text", text: `Agent registered:
+
+${formatAgent(agent)}
+
+\u26A0\uFE0F Save the API key \u2014 it won't be shown again.` }]
+      };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@delega-dev/mcp",
+  "version": "1.0.1",
+  "description": "MCP server for Delega \u2014 task infrastructure for AI agents",
+  "type": "module",
+  "bin": {
+    "delega-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "delega",
+    "tasks",
+    "ai-agents",
+    "delegation",
+    "model-context-protocol",
+    "task-management",
+    "agent-infrastructure"
+  ],
+  "author": "Delega Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delega-dev/delega-mcp"
+  },
+  "homepage": "https://delega.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}