MCP Backlog Server

Instructions

Implementation Reference

• src/index.ts:394-442 (handler)

  Primary handler function executing the todo-write tool logic, handling create, update, and list actions for backlog todos using shared utilities.

  async function handleBacklogTodoWrite(args: any) {
    const { action, topic, todoId, content, status, dependencies, batch } = args;
    if (!topic) throw new Error("topic is required");
  
    switch (action) {
      case "create": {
        if (!content) throw new Error("content is required for create action");
        
        const data = readTodos(topic);
        const newTodo = {
          id: crypto.randomUUID(),
          content,
          status: status || "pending",
          dependencies: dependencies || [],
          batch: batch || null,
          created: new Date().toISOString(),
          agent: "mcp-backlog",
          session: crypto.randomUUID(),
        };
        
        data.todos.push(newTodo);
        writeTodos(topic, data);
        return `Created todo: ${newTodo.id}`;
      }
  
      case "update": {
        if (!todoId) throw new Error("todoId is required for update action");
        
        const data = readTodos(topic);
        const todo = data.todos.find(t => t.id === todoId);
        if (!todo) throw new Error(`Todo not found: ${todoId}`);
        
        if (content !== undefined) todo.content = content;
        if (status !== undefined) todo.status = status as any;
        if (dependencies !== undefined) todo.dependencies = dependencies;
        if (batch !== undefined) todo.batch = batch;
        
        writeTodos(topic, data);
        return `Updated todo: ${todoId}`;
      }
  
      case "list": {
        return await handleBacklogTodoRead({ topic, status, batch });
      }
  
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }

• src/index.ts:746-782 (schema)

  Input schema defining parameters and validation for the todo-write tool.

  inputSchema: {
    type: "object",
    properties: {
      action: {
        type: "string",
        enum: ["create", "update", "list"],
        description: "Operation to perform",
      },
      topic: {
        type: "string",
        description: "Topic name (required)",
      },
      todoId: {
        type: "string",
        description: "Todo ID (required for update)",
      },
      content: {
        type: "string",
        description: "Todo content",
      },
      status: {
        type: "string",
        enum: ["pending", "in_progress", "completed", "cancelled"],
        description: "Todo status",
      },
      dependencies: {
        type: "array",
        items: { type: "string" },
        description: "Todo dependencies (array of todo IDs)",
      },
      batch: {
        type: "string",
        description: "Batch identifier",
      },
    },
    required: ["action", "topic"],
  },

• src/index.ts:743-783 (registration)

  Tool registration in the ListToolsRequestSchema handler, including name, description, and schema.

  {
    name: "todo-write",
    description: "Write access to backlog todos - create and update todos for backlog items",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["create", "update", "list"],
          description: "Operation to perform",
        },
        topic: {
          type: "string",
          description: "Topic name (required)",
        },
        todoId: {
          type: "string",
          description: "Todo ID (required for update)",
        },
        content: {
          type: "string",
          description: "Todo content",
        },
        status: {
          type: "string",
          enum: ["pending", "in_progress", "completed", "cancelled"],
          description: "Todo status",
        },
        dependencies: {
          type: "array",
          items: { type: "string" },
          description: "Todo dependencies (array of todo IDs)",
        },
        batch: {
          type: "string",
          description: "Batch identifier",
        },
      },
      required: ["action", "topic"],
    },
  },

• src/index.ts:840-845 (registration)

  Dispatch registration for todo-write tool in the CallToolRequestSchema switch statement.

  case "todo-write":
    result = await handleBacklogTodoWrite(request.params.arguments);
    break;
  case "todo-done":
    result = await handleBacklogTodoDone(request.params.arguments);
    break;

• src/index.ts:23-27 (helper)

  Import of helper functions from backlog-todo-shared.js used by the todo-write handler for reading/writing todos.

    readTodos,
    writeTodos,
    listTodos,
    validateDependencies
  } from '../lib/backlog-todo-shared.js';