Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/KnowledgeToolHandler.ts:401-490 (handler)

  Async handler function that implements the get_knowledge_file tool logic: locates the project and file, reads content, parses metadata and chapters, handles errors, and formats the response.

  async getKnowledgeFileAsync(params: {
    project_id: z.infer<typeof secureProjectIdSchema>;
    filename: z.infer<typeof secureFilenameSchema>;
  }): Promise<string> {
    const context = this.createContext('get_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 and read it
      let content: string;
      try {
        content = await readFile(filePath, 'utf8');
      } 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;
      }
  
      const [metadata, body] = parseDocument(content);
  
      // Parse chapters from body
      const chapters = body
        .split(/^## /m)
        .slice(1)
        .map((chapterText) => {
          const lines = chapterText.split('\n');
          const title = lines[0].trim();
          const content = lines.slice(1).join('\n').trim();
  
          return {
            title,
            content,
            summary: content.split('\n')[0].slice(0, 100) + '...',
          };
        });
  
      this.logSuccess('get_knowledge_file', { project_id, filename }, context);
      return this.formatSuccessResponse({
        document: {
          filename,
          metadata,
          full_content: body,
          chapters,
        },
      });
    } catch (error) {
      const mcpError =
        error instanceof MCPError
          ? error
          : new MCPError(
              MCPErrorCode.DOCUMENT_NOT_FOUND,
              `Failed to get knowledge file: ${error instanceof Error ? error.message : String(error)}`,
              {
                project_id: params.project_id,
                filename: params.filename,
                traceId: context.traceId,
              }
            );
      this.logError(
        'get_knowledge_file',
        {
          project_id: params.project_id,
          filename: params.filename,
        },
        mcpError,
        context
      );
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:255-276 (registration)

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

  server.registerTool(
    'get_knowledge_file',
    {
      title: 'Get Knowledge File',
      description: TOOL_DESCRIPTIONS.get_knowledge_file,
      inputSchema: {
        project_id: secureProjectIdSchema.describe('The project identifier'),
        filename: secureFilenameSchema.describe('Knowledge file name (must include .md extension)'),
      },
    },
    async ({ project_id, filename }) => {
      const result = await knowledgeHandler.getKnowledgeFileAsync({ project_id, filename });
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/config/toolDescriptions.ts:221-249 (schema)

  Defines the detailed natural language description and usage instructions for the get_knowledge_file tool, referenced in the registration.

    get_knowledge_file: `Retrieve complete content of a knowledge document including all metadata and chapters.
  
  When to use this tool:
  - Needing full document for comprehensive review
  - Backing up or exporting documents
  - Migrating content between projects
  - Loading small documents completely
  
  Key features:
  - Returns complete document with all chapters
  - Includes metadata (title, keywords, introduction)
  - Preserves document structure
  - Full content access
  
  You should:
  1. Consider using chapter operations for large documents
  2. Check document exists first
  3. Include .md extension in filename
  4. Be aware this loads entire document into memory
  5. Use chapter iteration for partial access
  6. Cache result if accessing multiple times
  
  DO NOT use when:
  - Only need specific chapters (use get_chapter)
  - Document is very large (use chapter operations)
  - Just need to search content (use search_knowledge)
  
  Returns: {success: bool, document?: object, error?: str}`,