Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/ProjectToolHandler.ts:588-697 (handler)

  Asynchronous implementation of the tool handler. Locates the specified section header (## ) in the project's main.md file, replaces the section content with new_content, updates the file, auto-commits the change, and returns a formatted response.

  /**
   * Async version of updateProjectSection
   */
  async updateProjectSectionAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    section_header: z.infer<typeof secureSectionHeaderSchema>;
    new_content: z.infer<typeof secureContentSchema>;
  }): Promise<string> {
    const context = this.createContext('update_project_section', params);
  
    try {
      const { project_id, section_header, new_content } = params;
      const projectInfo = await getProjectDirectoryAsync(this.storagePath, project_id);
  
      // Check if project exists
      if (!projectInfo) {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${project_id} not found`, {
          project_id,
          traceId: context.traceId,
        });
      }
  
      const [originalId, projectPath] = projectInfo;
      const mainFile = join(projectPath, 'main.md');
  
      try {
        await access(mainFile);
      } catch {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${originalId} does not exist`, {
          project_id,
          section_header,
          traceId: context.traceId,
        });
      }
  
      const content = await readFile(mainFile, 'utf8');
      const lines = content.split('\n');
  
      // Find the section
      let sectionStart = -1;
      let sectionEnd = lines.length;
  
      for (let i = 0; i < lines.length; i++) {
        if (lines[i].trim() === section_header.trim()) {
          sectionStart = i;
          // Find the end of this section (next ## header or end of file)
          for (let j = i + 1; j < lines.length; j++) {
            if (lines[j].startsWith('## ')) {
              sectionEnd = j;
              break;
            }
          }
          break;
        }
      }
  
      if (sectionStart === -1) {
        throw new MCPError(
          MCPErrorCode.SECTION_NOT_FOUND,
          `Section "${section_header}" not found in project main`,
          { project_id, section_header, traceId: context.traceId }
        );
      }
  
      // Replace the section content
      const newLines = [
        ...lines.slice(0, sectionStart + 1),
        '',
        new_content,
        '',
        ...lines.slice(sectionEnd),
      ];
  
      const updatedContent = newLines.join('\n');
      await writeFile(mainFile, updatedContent);
  
      await autoCommitAsync(
        this.storagePath,
        `Update section "${section_header}" in ${originalId}`
      );
  
      await this.logSuccessAsync('update_project_section', { project_id, section_header }, context);
      return this.formatSuccessResponse({
        message: `Section "${section_header}" updated in project ${originalId}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.INTERNAL_ERROR,
              `Failed to update project section: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                section_header: params.section_header,
                traceId: context.traceId,
              }
            );
      await this.logErrorAsync(
        'update_project_section',
        {
          project_id: params.project_id,
          section_header: params.section_header,
        },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:93-123 (registration)

  Registers the 'update_project_section' tool with the MCP server, specifying title, description, input schema, and the handler invocation.

  server.registerTool(
    'update_project_section',
    {
      title: 'Update Project Section',
      description: TOOL_DESCRIPTIONS.update_project_section,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        section_header: secureSectionHeaderSchema.describe(
          'The exact section header to update (e.g., "## Installation")'
        ),
        new_content: secureContentSchema.describe(
          'The new content for this section (without the header)'
        ),
      },
    },
    async ({ project_id, section_header, new_content }) => {
      const result = await projectHandler.updateProjectSectionAsync({
        project_id,
        section_header,
        new_content,
      });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/schemas/validation.ts:4-44 (schema)

  Zod schema definitions for input parameters: secureProjectIdSchema, secureContentSchema, and secureSectionHeaderSchema used for validating project_id, new_content, and section_header.

  export const secureProjectIdSchema = z
    .string()
    .min(1, 'Project ID cannot be empty')
    .max(100, 'Project ID too long')
    .refine(
      (val) => !val.includes('..') && !val.startsWith('.') && !val.endsWith('.'),
      'Project ID cannot contain path traversal patterns'
    )
    .refine(
      (val) => !/[/\\:*?"<>|\0]/.test(val),
      'Project ID cannot contain filesystem reserved characters or null bytes'
    )
    .refine((val) => val.trim() === val, 'Project ID cannot have leading/trailing spaces');
  
  export const secureFilenameSchema = z
    .string()
    .min(1, 'Filename cannot be empty')
    .max(255, 'Filename too long')
    .refine(
      (val) => !val.includes('/') && !val.includes('\\') && !val.includes('\0'),
      'Filename contains invalid path characters'
    )
    .refine(
      (val) => !val.includes('..') && val.trim() === val,
      'Filename cannot contain path traversal or leading/trailing spaces'
    );
  
  export const secureContentSchema = z
    .string()
    .max(10 * 1024 * 1024, 'Content too large (max 10MB)')
    .refine((val) => !val.includes('\0'), 'Content cannot contain null bytes');
  
  export const secureSectionHeaderSchema = z
    .string()
    .min(1, 'Section header cannot be empty')
    .max(200, 'Section header too long')
    .regex(/^##\s+/, 'Section header must start with "## "')
    .refine(
      (val) => !val.includes('\0') && val.trim() === val,
      'Section header contains invalid characters'
    );