Backlog MCP Server

Instructions

Implementation Reference

• packages/server/src/tools/backlog-get.ts:20-53 (handler)

  The main implementation of backlog_get tool. Includes the fetchItem helper function (lines 20-33) that retrieves either tasks by ID or resources by MCP URI, and the registerBacklogGetTool function (lines 35-53) that registers the tool with the MCP server and handles the async execution logic with support for batch fetching multiple IDs.

  function fetchItem(id: string): string {
    if (isResourceUri(id)) {
      const resource = storage.getResource(id);
      if (!resource) return `Not found: ${id}`;
      // Return resource with metadata header for agent context
      const header = `# Resource: ${id}\nMIME: ${resource.mimeType}`;
      const frontmatterStr = resource.frontmatter
        ? `\nFrontmatter: ${JSON.stringify(resource.frontmatter)}`
        : '';
      return `${header}${frontmatterStr}\n\n${resource.content}`;
    }
  
    return storage.getMarkdown(id) || `Not found: ${id}`;
  }
  
  export function registerBacklogGetTool(server: McpServer) {
    server.registerTool(
      'backlog_get',
      {
        description: 'Get full details by ID. Accepts task IDs (TASK-0001, EPIC-0002) or MCP resource URIs (mcp://backlog/resources/design.md). Works for any item regardless of status.',
        inputSchema: z.object({
          id: z.union([z.string(), z.array(z.string())]).describe('Task ID (e.g. TASK-0001) or MCP resource URI (e.g. mcp://backlog/resources/file.md). Array for batch fetch.'),
        }),
      },
      async ({ id }) => {
        const ids = Array.isArray(id) ? id : [id];
        if (ids.length === 0) {
          return { content: [{ type: 'text', text: 'Required: id' }], isError: true };
        }
        const results = ids.map(fetchItem);
        return { content: [{ type: 'text', text: results.join('\n\n---\n\n') }] };
      }
    );
  }

• packages/server/src/tools/backlog-get.ts:38-43 (schema)

  Zod schema definition for the backlog_get tool input. Accepts either a single string (task ID like TASK-0001 or MCP resource URI like mcp://backlog/resources/file.md) or an array of strings for batch fetching. Includes description explaining the tool's purpose.

  {
    description: 'Get full details by ID. Accepts task IDs (TASK-0001, EPIC-0002) or MCP resource URIs (mcp://backlog/resources/design.md). Works for any item regardless of status.',
    inputSchema: z.object({
      id: z.union([z.string(), z.array(z.string())]).describe('Task ID (e.g. TASK-0001) or MCP resource URI (e.g. mcp://backlog/resources/file.md). Array for batch fetch.'),
    }),
  },

• packages/server/src/tools/index.ts:3-12 (registration)

  Registration of the backlog_get tool in the main tools index. Imports registerBacklogGetTool from backlog-get.js and calls it within registerTools function to register the tool with the MCP server.

  import { registerBacklogGetTool } from './backlog-get.js';
  import { registerBacklogCreateTool } from './backlog-create.js';
  import { registerBacklogUpdateTool } from './backlog-update.js';
  import { registerBacklogDeleteTool } from './backlog-delete.js';
  import { registerBacklogSearchTool } from './backlog-search.js';
  import { registerBacklogContextTool } from './backlog-context.js';
  
  export function registerTools(server: McpServer) {
    registerBacklogListTool(server);
    registerBacklogGetTool(server);

• packages/server/src/storage/backlog-service.ts:52-54 (helper)

  Storage helper method getMarkdown that retrieves markdown content for tasks by ID. Used by the backlog_get handler to fetch task details.

  getMarkdown(id: string): string | null {
    return this.taskStorage.getMarkdown(id);
  }

• packages/server/src/storage/backlog-service.ts:113-119 (helper)

  Storage helper method getResource that retrieves resources by MCP URI. Used by the backlog_get handler to fetch resource content with metadata (content, frontmatter, mimeType). Part of ADR-0073 implementation for unified resource access.

  getResource(uri: string): { content: string; frontmatter?: Record<string, any>; mimeType: string } | undefined {
    try {
      return resourceManager.read(uri);
    } catch {
      return undefined;
    }
  }