Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/TodoToolHandler.ts:1001-1060 (handler)

  Main handler implementation for complete_todo_task tool. Locates the project and TODO directory, finds the specific task file, updates its frontmatter metadata to set completed=true with timestamp, auto-commits the change to git, and returns success response.

  async completeTodoTaskAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    todo_number: z.infer<typeof secureTodoNumberSchema>;
    task_number: z.infer<typeof secureTodoNumberSchema>;
  }): Promise<string> {
    const context = this.createContext('complete_todo_task', params);
  
    try {
      const { project_id, todo_number, task_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 task file
      const taskFile = await this.findTaskFileAsync(todoDir, task_number);
      if (!taskFile) {
        throw new MCPError(
          MCPErrorCode.TASK_NOT_FOUND,
          `Task #${task_number} not found in TODO #${todo_number}`,
          { project_id, todo_number, task_number, traceId: context.traceId }
        );
      }
  
      // Update task metadata
      await this.updateTaskMetadataAsync(join(todoDir, taskFile), { completed: true });
  
      // Auto-commit
      await autoCommitAsync(
        this.storagePath,
        `Complete task #${task_number} in TODO #${todo_number}`
      );
  
      this.logSuccess('complete_todo_task', params, context);
      return this.formatSuccessResponse({
        message: `Marked task #${task_number} as completed in TODO #${todo_number}`,
      });
    } catch (error) {
      this.logError('complete_todo_task', params, error as MCPError, context);
      return this.formatErrorResponse(error, context);
    }
  }

• src/knowledge-mcp/server.ts:712-737 (registration)

  MCP tool registration for 'complete_todo_task', defining input schema using Zod schemas, title, description from TOOL_DESCRIPTIONS, and handler that delegates to todoHandler.completeTodoTaskAsync.

    'complete_todo_task',
    {
      title: 'Complete TODO Task',
      description: TOOL_DESCRIPTIONS.complete_todo_task,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        todo_number: secureTodoNumberSchema.describe('The TODO list number'),
        task_number: secureTodoNumberSchema.describe('The task number to complete'),
      },
    },
    async ({ project_id, todo_number, task_number }) => {
      const result = await todoHandler.completeTodoTaskAsync({
        project_id,
        todo_number,
        task_number,
      });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:585-614 (schema)

  Detailed description string for the complete_todo_task tool used in registration, providing usage guidelines, when to use, key features, and return format.

    complete_todo_task: `Mark a task as completed in a TODO list.
  
  When to use this tool:
  - Task implementation is fully complete
  - Task requirements are met
  - Moving to next task in sequence
  - Updating progress status
  - Recording completion for tracking
  
  Key features:
  - Marks task with completion timestamp
  - Updates TODO completion percentage
  - Preserves task content and history
  - Cannot be undone
  
  You should:
  1. ONLY mark complete when truly finished
  2. Verify task is actually done
  3. Test/validate before marking complete
  4. Complete tasks as you finish them
  5. Don't batch completions
  6. Move to next task after completing
  
  DO NOT use when:
  - Task is partially complete
  - Work is blocked or paused
  - Need to revisit later
  - Implementation failed
  
  Returns: {success: bool, message: str, error?: str}`,

• src/knowledge-mcp/handlers/TodoToolHandler.ts:1324-1342 (helper)

  Helper method called by the handler to update the task's YAML frontmatter metadata (sets completed: true and updated timestamp) while preserving the markdown body content.

  private async updateTaskMetadataAsync(
    filepath: string,
    updates: Partial<TaskMetadata>
  ): Promise<void> {
    const content = await readFile(filepath, 'utf8');
    const parsed = fm<TaskMetadata>(content);
  
    // Update metadata
    const updatedMetadata: TaskMetadata = {
      ...parsed.attributes,
      ...updates,
      updated: new Date().toISOString(),
    };
  
    // Write back with updated metadata
    const frontmatter = yaml.dump(updatedMetadata);
    const updatedContent = `---\n${frontmatter}---\n${parsed.body}`;
    await writeFile(filepath, updatedContent);
  }