MCP Backlog Server

Instructions

Implementation Reference

• src/index.ts:92-113 (handler)

  Main handler function for the "write" MCP tool. Dispatches to sub-handlers based on the 'action' parameter (create, amend, submit, etc.).

  async function handleBacklogWrite(args: any, context: any) {
    const action = args.action || "create";
  
    switch (action) {
      case "create":
        return await handleCreate(args, context);
      case "list":
        return await listBacklogItems(args);
      case "amend":
        return await handleAmend(args, context);
      case "submit":
        return await handleSubmit(args, context);
      case "approve":
        return await handleApprove(args, context);
      case "reopen":
        return await handleReopen(args, context);
      case "wontfix":
        return await handleWontfix(args, context);
      default:
        throw new Error(`Unknown action: ${action}`);
    }
  }

• src/index.ts:659-686 (schema)

  Input schema definition for the "write" tool, specifying parameters like action, topic, description, priority, and status.

  inputSchema: {
    type: "object",
    properties: {
      action: {
        type: "string",
        enum: ["create", "list", "amend", "approve", "submit", "reopen", "wontfix"],
        description: "Operation to perform (default: create)",
      },
      topic: {
        type: "string",
        description: "Topic name (required for create/amend)",
      },
      description: {
        type: "string",
        description: "Description (required for create, optional for amend)",
      },
      priority: {
        type: "string",
        enum: ["high", "medium", "low"],
        description: "Priority level for create/amend operations (default: medium)",
      },
      status: {
        type: "string",
        enum: ["new", "ready", "review", "done", "reopen", "wontfix"],
        description: "Status for amend operation or filter for list operation",
      },
    },
  },

• src/index.ts:832-833 (registration)

  Handler dispatch registration for the "write" tool in the CallToolRequestSchema switch statement.

  result = await handleBacklogWrite(request.params.arguments, context);
  break;

• src/index.ts:656-687 (registration)

  Tool metadata and schema registration for "write" in the ListToolsRequestSchema response.

  {
    name: "write",
    description: "Write access to backlog management - create, amend, and list backlog work items",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["create", "list", "amend", "approve", "submit", "reopen", "wontfix"],
          description: "Operation to perform (default: create)",
        },
        topic: {
          type: "string",
          description: "Topic name (required for create/amend)",
        },
        description: {
          type: "string",
          description: "Description (required for create, optional for amend)",
        },
        priority: {
          type: "string",
          enum: ["high", "medium", "low"],
          description: "Priority level for create/amend operations (default: medium)",
        },
        status: {
          type: "string",
          enum: ["new", "ready", "review", "done", "reopen", "wontfix"],
          description: "Status for amend operation or filter for list operation",
        },
      },
    },
  },

• src/index.ts:115-139 (helper)

  Example helper function called by the write handler for the 'create' action, handling new backlog item creation.

  async function handleCreate(args: any, context: any) {
    const { topic, description, priority = "medium" } = args;
  
    if (!topic || !description) {
      throw new Error("topic and description are required for create action");
    }
  
    const filename = generateBacklogFilename(topic);
    const backlogDir = getBacklogDir();
    const dirpath = `${backlogDir}/${filename}`;
    const filepath = `${dirpath}/item.md`;
  
     const newExists = await fileExists(filepath);
     const legacyPath = `${backlogDir}/${filename}.md`;
     const legacyExists = await fileExists(legacyPath);
     
     if (newExists || legacyExists) {
       throw new Error(`Backlog item already exists. Use 'amend' to update it.`);
     }
  
     const content = createBacklogTemplate(topic, description, priority, context);
     mkdirSync(dirpath, { recursive: true });
     await writeFile(filepath, content);
    return `Created backlog item: ${filepath}`;
  }