MCP Backlog Server

Instructions

Implementation Reference

• src/index.ts:313-378 (handler)

  Core handler function that implements the 'done' tool logic: locates the backlog item, updates its status to 'done' or 'wontfix' based on content, adds completion metadata and optional summary, archives it to the completed directory, and removes it from the active backlog.

  async function handleDone(args: any, context: any) {
    const { topic, summary } = args;
  
    if (!topic) {
      throw new Error("topic is required for done action");
    }
  
    const filename = topic
      .toLowerCase()
      .replace(/\s+/g, "-")
      .replace(/[^a-z0-9-]/g, "");
    const backlogDir = getBacklogDir();
    const filepath = `${backlogDir}/${filename}/item.md`;
    const legacyPath = `${backlogDir}/${filename}.md`;
  
     let actualPath: string | null = null;
     const newExists = await fileExists(filepath);
     const legacyExists = await fileExists(legacyPath);
     
     if (newExists) {
       actualPath = filepath;
     } else if (legacyExists) {
       actualPath = legacyPath;
     } else {
       throw new Error(`Backlog item not found for topic: ${topic}`);
     }
  
     let content = await readFile(actualPath, 'utf8');
    
    let finalStatus = 'done';
    if (content.startsWith('---\n')) {
      const statusMatch = content.match(/status: (wontfix|done)/);
      if (statusMatch) {
        finalStatus = statusMatch[1];
      }
    }
  
    if (content.startsWith('---\n')) {
      content = content.replace(/status: .*/, `status: ${finalStatus}`);
    } else {
      content = content.replace(/## Status: .*/, `## Status: ${finalStatus}`);
    }
  
    const timestamp = new Date().toISOString();
    let completionSection = `\n## Completed\n- Date: ${timestamp}\n- Agent: ${context.agent}\n- Session: ${context.sessionID}\n`;
    
    if (summary) {
      completionSection += `\n### Summary\n\n${summary}\n`;
    }
  
    content = content.replace(/\n---\n/, `${completionSection}\n---\n`);
  
     const prefix = finalStatus === 'wontfix' ? 'WONTFIX' : 'DONE';
     const completedDir = getCompletedBacklogDir();
     const completedPath = `${completedDir}/${prefix}_${filename}.md`;
     await writeFile(completedPath, content, 'utf8');
  
    if (actualPath === filepath) {
      const dirpath = `${backlogDir}/${filename}`;
      rmSync(dirpath, { recursive: true, force: true });
    } else {
      unlinkSync(actualPath);
    }
  
    return `Marked backlog item as ${finalStatus}: ${completedPath}${summary ? ' (with summary)' : ''}`;
  }

• src/index.ts:689-719 (schema)

  Input schema and metadata for the 'done' tool as returned in ListTools response.

    name: "done",
    description: "Mark backlog items as complete with optional summary - done operation and list",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["done", "list"],
          description: "Operation to perform (default: done)",
        },
        topic: {
          type: "string",
          description: "Topic name (required for done)",
        },
        summary: {
          type: "string",
          description: "Optional completion summary describing what was accomplished, lessons learned, or final notes",
        },
        status: {
          type: "string",
          enum: ["new", "ready", "review", "done", "reopen", "wontfix"],
          description: "Status filter for list operation",
        },
        priority: {
          type: "string",
          enum: ["high", "medium", "low"],
          description: "Priority filter for list operation",
        },
      },
    },
  },

• src/index.ts:834-836 (registration)

  Registration of the 'done' tool handler in the MCP CallToolRequestSchema switch statement, delegating to handleBacklogDone.

  case "done":
    result = await handleBacklogDone(request.params.arguments, context);
    break;

• src/index.ts:299-311 (handler)

  Dispatcher handler for the 'done' tool that routes 'done' action to handleDone and 'list' to listBacklogItems.

  // Backlog Done Handler
  async function handleBacklogDone(args: any, context: any) {
    const action = args.action || "done";
  
    switch (action) {
      case "done":
        return await handleDone(args, context);
      case "list":
        return await listBacklogItems(args);
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }