Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/TodoToolHandler.ts:864-932 (handler)

  Executes the 'add_todo_task' tool logic: validates input, ensures project and TODO exist, generates next task number and filename, creates markdown task file with YAML frontmatter metadata (created/updated timestamps, incomplete status), title header, and optional content, auto-commits changes to git storage.

  async addTodoTaskAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    todo_number: z.infer<typeof secureTodoNumberSchema>;
    title: z.infer<typeof secureTaskTitleSchema>;
    content?: z.infer<typeof secureTaskContentSchema>;
  }): Promise<string> {
    const context = this.createContext('add_todo_task', params);
  
    try {
      const { project_id, todo_number, title, content = '' } = params;
      const [, projectPath] = await createProjectEntryAsync(this.storagePath, project_id);
      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,
        });
      }
  
      // Get next task number
      const taskNumber = await this.getNextTaskNumberAsync(todoDir);
      const taskFilename = `TASK-${taskNumber.toString().padStart(3, '0')}-${slugify(title, { lower: true, strict: true })}.md`;
  
      // Create task metadata
      const metadata: TaskMetadata = {
        completed: false,
        created: new Date().toISOString(),
        updated: new Date().toISOString(),
      };
  
      // Write task file
      const frontmatter = yaml.dump(metadata);
      const taskContent = `---\n${frontmatter}---\n\n# ${title}\n\n${content || ''}`;
      await writeFile(join(todoDir, taskFilename), taskContent);
  
      // Auto-commit
      await autoCommitAsync(this.storagePath, `Add task "${title}" to TODO #${todo_number}`);
  
      this.logSuccess(
        'add_todo_task',
        { project_id, todo_number, task_number: taskNumber },
        context
      );
      return this.formatSuccessResponse({
        task_number: taskNumber,
        message: `Added task #${taskNumber} to TODO #${todo_number}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to add task: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                todo_number: params.todo_number,
                traceId: context.traceId,
              }
            );
      this.logError('add_todo_task', params, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:661-685 (registration)

  Registers the MCP tool 'add_todo_task' with input schema validation, human-readable title and detailed description, delegating execution to TodoToolHandler.addTodoTaskAsync method and formatting response as MCP content.

    'add_todo_task',
    {
      title: 'Add TODO Task',
      description: TOOL_DESCRIPTIONS.add_todo_task,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        todo_number: secureTodoNumberSchema.describe('The TODO list number'),
        title: secureTaskTitleSchema.describe('Brief task title (max 200 chars, used in filename)'),
        content: secureTaskContentSchema.describe(
          'Full markdown content with implementation details, code examples, etc.'
        ),
      },
    },
    async (params) => {
      const result = await todoHandler.addTodoTaskAsync(params);
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/schemas/validation.ts:92-118 (schema)

  Zod schemas for input validation specific to TODO tasks: secureTodoNumberSchema (positive integer), secureTaskTitleSchema (1-200 chars, trimmed, no null bytes), secureTaskContentSchema (optional up to 100KB markdown, no null bytes). Used in tool inputSchema and method signatures.

  export const secureTodoNumberSchema = z
    .number()
    .int('TODO number must be an integer')
    .positive('TODO number must be positive')
    .max(99999, 'TODO number too large');
  
  export const secureTodoDescriptionSchema = z
    .string()
    .min(1, 'TODO description cannot be empty')
    .max(500, 'TODO description too long (max 500 characters)')
    .refine((val) => !val.includes('\0'), 'TODO description cannot contain null bytes')
    .refine((val) => val.trim() === val, 'TODO description cannot have leading/trailing spaces');
  
  // Task title for brief identification (used in filenames)
  export const secureTaskTitleSchema = z
    .string()
    .min(1, 'Task title cannot be empty')
    .max(200, 'Task title too long (max 200 characters)')
    .refine((val) => !val.includes('\0'), 'Task title cannot contain null bytes')
    .refine((val) => val.trim() === val, 'Task title cannot have leading/trailing spaces');
  
  // Full markdown content for task details
  export const secureTaskContentSchema = z
    .string()
    .max(100 * 1024, 'Task content too large (max 100KB)')
    .refine((val) => !val.includes('\0'), 'Task content cannot contain null bytes')
    .optional();