Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/ProjectToolHandler.ts:540-586 (handler)

  The core asynchronous handler function that executes the tool logic: creates project directory if needed, writes content to main.md, auto-commits changes to git, handles errors with MCPError.

  async updateProjectMainAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    content: z.infer<typeof secureContentSchema>;
  }): Promise<string> {
    const context = this.createContext('update_project_main', params);
  
    try {
      const { project_id, content } = params;
      // Use createProjectEntryAsync for write operations that create new projects
      const [originalId, projectPath] = await createProjectEntryAsync(this.storagePath, project_id);
  
      // Create project directory if it doesn't exist
      await mkdir(projectPath, { recursive: true });
  
      // Write main.md file
      const validatedPath = await validatePathAsync(projectPath, 'main.md');
      await writeFile(validatedPath, content);
  
      // Auto-commit changes
      await autoCommitAsync(this.storagePath, `Update project main for ${originalId}`);
  
      await this.logSuccessAsync('update_project_main', { project_id }, context);
      return this.formatSuccessResponse({
        message: `Project main updated for ${originalId}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to update project main: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                method: 'update_project_main',
                traceId: context.traceId,
              }
            );
      await this.logErrorAsync(
        'update_project_main',
        { project_id: params.project_id },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:70-91 (registration)

  Registers the 'update_project_main' tool with the MCP server, defining input schema using Zod schemas, tool description, title, and wiring the async handler.

  server.registerTool(
    'update_project_main',
    {
      title: 'Update Project Main',
      description: TOOL_DESCRIPTIONS.update_project_main,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        content: secureContentSchema.describe('The new markdown content for main.md'),
      },
    },
    async ({ project_id, content }) => {
      const result = await projectHandler.updateProjectMainAsync({ project_id, content });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:32-61 (schema)

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

    update_project_main: `Create or completely replace main.md content for a project.
  
  When to use this tool:
  - Migrating CLAUDE.md content to centralized MCP storage
  - Creating a new project's instruction set
  - Completely rewriting project guidelines
  - Setting up initial project configuration
  
  Key features:
  - Creates project if it doesn't exist (auto-initialization)
  - Completely replaces existing content (destructive update)
  - Automatically commits changes to git
  - Validates markdown structure
  
  You should:
  1. Check if project exists first with get_project_main
  2. Preserve important sections when doing full updates
  3. Use update_project_section for partial changes instead
  4. Include all necessary sections in the new content
  5. Validate markdown formatting before submission
  6. Consider the impact of complete replacement
  7. Document why full replacement is necessary
  
  DO NOT use when:
  - Making small updates (use update_project_section instead)
  - You haven't read the existing content first
  - Uncertain about losing existing content
  
  Returns: {success: bool, message?: str, error?: str}`,

• src/knowledge-mcp/handlers/ProjectToolHandler.ts:85-126 (handler)

  Synchronous version of the handler (similar logic using sync fs/git utils), provided for completeness though async is used in registration.

  updateProjectMain(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    content: z.infer<typeof secureContentSchema>;
  }): string {
    const context = this.createContext('update_project_main', params);
  
    try {
      const { project_id, content } = params;
      // Use createProjectEntry for write operations that create new projects
      const [originalId, projectPath] = createProjectEntry(this.storagePath, project_id);
  
      // Create project directory if it doesn't exist
      mkdirSync(projectPath, { recursive: true });
  
      // Write main.md file
      const validatedPath = validatePath(projectPath, 'main.md');
      writeFileSync(validatedPath, content);
  
      // Auto-commit changes
      autoCommit(this.storagePath, `Update project main for ${originalId}`);
  
      this.logSuccess('update_project_main', { project_id }, context);
      return this.formatSuccessResponse({
        message: `Project main updated for ${originalId}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to update project main: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                method: 'update_project_main',
                traceId: context.traceId,
              }
            );
      this.logError('update_project_main', { project_id: params.project_id }, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }