MCP Backlog Server

Instructions

Implementation Reference

• src/index.ts:381-391 (handler)

  The primary handler function for the "todo-read" MCP tool. It validates input, constructs filters, calls listTodos helper, and returns JSON serialized todos.

  async function handleBacklogTodoRead(args: any) {
    const { topic, status, batch } = args;
    if (!topic) throw new Error("topic is required");
  
    const filters: any = {};
    if (status) filters.status = status;
    if (batch) filters.batch = batch;
  
    const todos = listTodos(topic, filters);
    return JSON.stringify(todos, null, 2);
  }

• src/index.ts:721-742 (schema)

  Input schema definition for the "todo-read" tool, defining required 'topic' and optional 'status'/'batch' filters.

    name: "todo-read",
    description: "Read-only access to backlog todos - list and filter todos for a backlog item",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          description: "Topic name (required)",
        },
        status: {
          type: "string",
          enum: ["pending", "in_progress", "completed", "cancelled"],
          description: "Filter by status",
        },
        batch: {
          type: "string",
          description: "Filter by batch",
        },
      },
      required: ["topic"],
    },
  },

• src/index.ts:720-742 (registration)

  Tool registration entry in the ListTools response, which exposes the "todo-read" tool to MCP clients with its schema.

  {
    name: "todo-read",
    description: "Read-only access to backlog todos - list and filter todos for a backlog item",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          description: "Topic name (required)",
        },
        status: {
          type: "string",
          enum: ["pending", "in_progress", "completed", "cancelled"],
          description: "Filter by status",
        },
        batch: {
          type: "string",
          description: "Filter by batch",
        },
      },
      required: ["topic"],
    },
  },

• lib/backlog-todo-shared.ts:102-115 (helper)

  Key helper function implementing todo listing and filtering logic by reading from todos.json and applying optional status and batch filters.

  export function listTodos(topic: string, filters?: { status?: string, batch?: string }): Todo[] {
    const data = readTodos(topic);
    let todos = data.todos;
  
    if (filters?.status) {
      todos = todos.filter(t => t.status === filters.status);
    }
  
    if (filters?.batch) {
      todos = todos.filter(t => t.batch === filters.batch);
    }
  
    return todos;
  }

• lib/backlog-todo-shared.ts:45-54 (helper)

  Helper function to read todos data from the JSON file for a given backlog topic, returning empty list if file missing.

  export function readTodos(topic: string): TodoData {
    const filePath = getTodosFilePath(topic);
    try {
      const content = readFileSync(filePath, 'utf8');
      return JSON.parse(content);
    } catch (error) {
      // File doesn't exist or is invalid, return empty structure
      return { backlogTopic: topic, todos: [] };
    }
  }