Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/KnowledgeToolHandler.ts:495-569 (handler)

  Implements the core logic for deleting a knowledge file asynchronously: validates project and file existence, deletes the file using unlink, auto-commits the change, logs success/error, and returns formatted response.

  async deleteKnowledgeFileAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    filename: z.infer<typeof secureFilenameSchema>;
  }): Promise<string> {
    const context = this.createContext('delete_knowledge_file', params);
  
    try {
      const { project_id, filename } = params;
      const projectInfo = await getProjectDirectoryAsync(this.storagePath, project_id);
  
      // Project doesn't exist - return error without creating ghost entry
      if (!projectInfo) {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${project_id} not found`, {
          project_id,
          filename,
          traceId: context.traceId,
        });
      }
  
      const [originalId, projectPath] = projectInfo;
      const knowledgePath = join(projectPath, 'knowledge');
      const filePath = join(knowledgePath, filename);
  
      // Check if file exists
      try {
        await access(filePath);
      } catch (error) {
        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
          throw new MCPError(
            MCPErrorCode.DOCUMENT_NOT_FOUND,
            `Knowledge file ${filename} not found in project ${originalId}`,
            { project_id, filename, traceId: context.traceId }
          );
        }
        throw error;
      }
  
      // Delete the file
      await unlink(filePath);
  
      // Auto-commit
      await autoCommitAsync(
        this.storagePath,
        `Delete knowledge file ${filename} from ${originalId}`
      );
  
      this.logSuccess('delete_knowledge_file', { project_id, filename }, context);
      return this.formatSuccessResponse({
        message: `Knowledge file ${filename} deleted from project ${originalId}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to delete knowledge file: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                filename: params.filename,
                traceId: context.traceId,
              }
            );
      this.logError(
        'delete_knowledge_file',
        {
          project_id: params.project_id,
          filename: params.filename,
        },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:279-299 (registration)

  Registers the 'delete_knowledge_file' tool with MCP server, defining title, description from TOOL_DESCRIPTIONS, input schema using secureProjectIdSchema and secureFilenameSchema, and handler that delegates to knowledgeHandler.deleteKnowledgeFileAsync.

    'delete_knowledge_file',
    {
      title: 'Delete Knowledge File',
      description: TOOL_DESCRIPTIONS.delete_knowledge_file,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        filename: secureFilenameSchema.describe('Full filename including .md extension'),
      },
    },
    async ({ project_id, filename }) => {
      const result = await knowledgeHandler.deleteKnowledgeFileAsync({ project_id, filename });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:250-275 (schema)

  Provides the detailed description string for the 'delete_knowledge_file' tool, used in the server registration, explaining usage, features, best practices, and warnings.

    delete_knowledge_file: `Permanently delete a knowledge document - this action cannot be undone.
  
  When to use this tool:
  - Document is obsolete or incorrect
  - Consolidating duplicate documents
  - Removing outdated information
  - Explicit request to delete
  
  Key features:
  - Complete removal of document
  - Removes from search index
  - Permanent deletion
  
  You should:
  1. Verify document exists first
  2. Check if content should be preserved elsewhere
  3. Confirm filename is correct (with .md extension)
  4. Understand deletion is permanent
  5. Consider if update would be better
  
  DO NOT use when:
  - Document might be useful later
  - Should be updated instead
  - Unsure about the impact
  
  Returns: {success: bool, message?: str, error?: str}`,

• src/knowledge-mcp/handlers/KnowledgeToolHandler.ts:223-289 (handler)

  Synchronous version of the delete knowledge file handler, similar logic using sync fs operations (existsSync, unlinkSync, etc.). Not directly called by server but available as fallback.

  deleteKnowledgeFile(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    filename: z.infer<typeof secureFilenameSchema>;
  }): string {
    const context = this.createContext('delete_knowledge_file', params);
  
    try {
      const { project_id, filename } = params;
      const projectInfo = getProjectDirectory(this.storagePath, project_id);
  
      // Project doesn't exist - return error without creating ghost entry
      if (!projectInfo) {
        throw new MCPError(MCPErrorCode.PROJECT_NOT_FOUND, `Project ${project_id} not found`, {
          project_id,
          filename,
          traceId: context.traceId,
        });
      }
  
      const [originalId, projectPath] = projectInfo;
      const knowledgePath = join(projectPath, 'knowledge');
      const filePath = join(knowledgePath, filename);
  
      // Check if file exists
      if (!existsSync(filePath)) {
        throw new MCPError(
          MCPErrorCode.DOCUMENT_NOT_FOUND,
          `Knowledge file ${filename} not found in project ${originalId}`,
          { project_id, filename, traceId: context.traceId }
        );
      }
  
      // Delete the file
      unlinkSync(filePath);
  
      // Auto-commit
      autoCommit(this.storagePath, `Delete knowledge file ${filename} from ${originalId}`);
  
      this.logSuccess('delete_knowledge_file', { project_id, filename }, context);
      return this.formatSuccessResponse({
        message: `Knowledge file ${filename} deleted from project ${originalId}`,
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.FILE_SYSTEM_ERROR,
              `Failed to delete knowledge file: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                filename: params.filename,
                traceId: context.traceId,
              }
            );
      this.logError(
        'delete_knowledge_file',
        {
          project_id: params.project_id,
          filename: params.filename,
        },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }