Backlog MCP Server

Instructions

Implementation Reference

• src/tools/getDocumentTree.ts:18-38 (handler)

  Factory function defining the 'get_document_tree' tool, including its handler that fetches the document tree via the Backlog API.

  export const getDocumentTreeTool = (
    backlog: Backlog,
    { t }: TranslationHelper
  ): ToolDefinition<
    ReturnType<typeof getDocumentTreeSchema>,
    typeof DocumentTreeFullSchema
  > => {
    return {
      name: 'get_document_tree',
      description: t(
        'TOOL_GET_DOCUMENT_TREE_DESCRIPTION',
        'Gets the document tree of a project.'
      ),
      schema: z.object(getDocumentTreeSchema(t)),
      outputSchema: DocumentTreeFullSchemaZ,
      importantFields: ['projectId', 'activeTree', 'trashTree'],
      handler: async ({ projectIdOrKey }) => {
        return backlog.getDocumentTree(projectIdOrKey);
      },
    };
  };

• src/tools/getDocumentTree.ts:10-16 (schema)

  Input schema definition for the tool's parameters using Zod.

  const getDocumentTreeSchema = buildToolSchema((t) => ({
    projectIdOrKey: z
      .union([z.string(), z.number()])
      .describe(
        t('TOOL_GET_DOCUMENT_TREE_PROJECT_ID_OR_KEY', 'Project ID or Key')
      ),
  }));

• src/types/zod/backlogOutputDefinition.ts:527-533 (schema)

  Output schema definition (Zod) for the document tree response.

  export const DocumentTreeFullSchema: z.ZodRawShape = {
    projectId: z.number(),
    activeTree: ActiveTrashTreeSchema.optional(),
    trashTree: ActiveTrashTreeSchema.optional(),
  };
  
  export const DocumentTreeFullSchemaZ = z.object(DocumentTreeFullSchema);

• src/tools/tools.ts:151-155 (registration)

  Registration of the get_document_tree tool within the 'document' toolset group in the allTools function.

  tools: [
    getDocumentsTool(backlog, helper),
    getDocumentTreeTool(backlog, helper),
    getDocumentTool(backlog, helper),
  ],