Claude Writer's Aid MCP

Instructions

Implementation Reference

• src/tools/WriterToolHandlers.ts:262-269 (handler)

  The primary MCP tool handler for 'find_todos'. Extracts parameters from args (scope, markers, groupBy, limit with pagination), then calls WritersAid.findTodos.

  private async findTodos(args: Record<string, unknown>) {
    const scope = args.scope as string | undefined;
    const markers = args.markers as string[] | undefined;
    const groupBy = args.group_by as "file" | "priority" | "marker" | undefined;
    const limit = resolvePaginationLimit("find_todos", args.limit as number | undefined);
  
    return this.writersAid.findTodos({ scope, markers, groupBy, limit });
  }

• src/tools/WriterToolDefinitions.ts:218-237 (schema)

  JSON schema defining the input parameters and structure for the 'find_todos' tool.

  name: "find_todos",
  description: "Extract all TODO/FIXME/DRAFT markers",
  inputSchema: {
    type: "object",
    properties: {
      project_path: { type: "string", description: "Path to manuscript directory (defaults to current directory)" },
      scope: { type: "string", description: "File scope pattern" },
      markers: {
        type: "array",
        items: { type: "string" },
        description: "Markers to search for",
      },
      group_by: {
        type: "string",
        enum: ["file", "priority", "marker"],
        description: "Grouping method",
      },
      limit: { type: "number", description: "Maximum results", default: 50 },
    },
  },

• src/tools/WriterToolHandlers.ts:48-49 (registration)

  Dispatch registration in the central handleTool switch statement that maps tool name 'find_todos' to its handler method.

  case "find_todos":
    return this.findTodos(args);

• src/quality/TodoExtractor.ts:19-54 (helper)

  Core helper function that implements TODO extraction logic: scans all file lines with regex for markers, extracts text and line numbers, assigns priority, and applies pagination.

  async findTodos(options: {
    scope?: string;
    markers?: string[];
    groupBy?: "file" | "priority" | "marker";
    limit?: number;
  }): Promise<TodoItem[]> {
    const { markers = ["TODO", "FIXME", "HACK", "XXX", "DRAFT", "WIP"], limit } = options;
  
    const files = await this.storage.getAllFiles();
    const todos: TodoItem[] = [];
  
    for (const file of files) {
      const lines = file.content.split("\n");
  
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
  
        for (const marker of markers) {
          const regex = new RegExp(`\\b${marker}\\b:?\\s*(.*)`, "i");
          const match = line.match(regex);
  
          if (match) {
            todos.push({
              file: file.file_path,
              line: i + 1,
              marker,
              text: match[1] || "",
              priority: this.determinePriority(marker),
            });
          }
        }
      }
    }
  
    return paginateResults(todos, limit);
  }