Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/TodoToolHandler.ts:1065-1132 (handler)

  The core handler function that implements the logic for 'get_next_todo_task'. It locates the next incomplete task in the specified TODO list by scanning task files, parsing metadata, and returning task details or completion status.

  async getNextTodoTaskAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    todo_number: z.infer<typeof secureTodoNumberSchema>;
  }): Promise<string> {
    const context = this.createContext('get_next_todo_task', params);
  
    try {
      const { project_id, todo_number } = params;
      const projectInfo = await getProjectDirectoryAsync(this.storagePath, project_id);
  
      if (!projectInfo) {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${project_id} not found`, {
          project_id,
          traceId: context.traceId,
        });
      }
  
      const [, projectPath] = projectInfo;
      const todoDir = join(projectPath, 'TODO', todo_number.toString());
  
      // Check if TODO exists
      try {
        await access(todoDir);
      } catch {
        throw new MCPError(MCPErrorCode.TODO_NOT_FOUND, `TODO #${todo_number} not found`, {
          project_id,
          todo_number,
          traceId: context.traceId,
        });
      }
  
      // Find all task files
      const taskFiles = await this.getTaskFilesAsync(todoDir);
  
      // Look for first incomplete task
      for (const taskFile of taskFiles) {
        const taskPath = join(todoDir, taskFile);
        const content = await readFile(taskPath, 'utf8');
        const parsed = fm<TaskMetadata>(content);
  
        if (!parsed.attributes.completed) {
          const taskNumber = this.extractTaskNumber(taskFile);
          const taskData = await this.parseTaskDataAsync(taskPath);
  
          this.logSuccess(
            'get_next_todo_task',
            { project_id, todo_number, task_number: taskNumber },
            context
          );
          return this.formatSuccessResponse({
            task: {
              number: taskNumber,
              description: taskData.title,
            },
          });
        }
      }
  
      // No incomplete tasks
      this.logSuccess('get_next_todo_task', { project_id, todo_number, found: false }, context);
      return this.formatSuccessResponse({
        message: 'All tasks completed',
      });
    } catch (error) {
      this.logError('get_next_todo_task', params, error as MCPError, context);
      return this.formatErrorResponse(error, context);
    }
  }

• src/knowledge-mcp/server.ts:740-760 (registration)

  Registers the 'get_next_todo_task' tool with the MCP server, specifying title, description, input schema, and the handler function that delegates to TodoToolHandler.getNextTodoTaskAsync.

    'get_next_todo_task',
    {
      title: 'Get Next TODO Task',
      description: TOOL_DESCRIPTIONS.get_next_todo_task,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        todo_number: secureTodoNumberSchema.describe('The TODO list number'),
      },
    },
    async ({ project_id, todo_number }) => {
      const result = await todoHandler.getNextTodoTaskAsync({ project_id, todo_number });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/server.ts:744-747 (schema)

  Defines the input schema for the tool using Zod schemas for project_id and todo_number with descriptions.

  inputSchema: {
    project_id: secureProjectIdSchema.describe('The project identifier'),
    todo_number: secureTodoNumberSchema.describe('The TODO list number'),
  },

• src/knowledge-mcp/handlers/TodoToolHandler.ts:621-624 (helper)

  Helper method to extract the task number from task filenames like 'TASK-001-slug.md', used in the handler to identify tasks.

  private extractTaskNumber(filename: string): number {
    const match = filename.match(/^TASK-(\d{3})-.*\.md$/);
    return match ? parseInt(match[1], 10) : 0;
  }

• src/knowledge-mcp/handlers/TodoToolHandler.ts:1344-1347 (helper)

  Async helper to list and sort task files (.md starting with TASK-) in a TODO directory, crucial for scanning tasks in the handler.

  private async getTaskFilesAsync(todoDir: string): Promise<string[]> {
    const files = await readdir(todoDir);
    return files.filter((file) => file.startsWith('TASK-') && file.endsWith('.md')).sort();
  }