load_document

Instructions

        Load and analyze a Markdown document from a file path.
        
        Args:
            document_path: Path to the Markdown file (supports absolute, relative, and ~ expansion)
            validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
        

Implementation Reference

• src/quantalogic_markdown_mcp/enhanced_mcp_server.py:24-48 (handler)

  Primary handler for the 'load_document' MCP tool in the enhanced server. Decorated with @self.mcp.tool() for automatic registration and schema inference. Loads document via processor, analyzes structure, and returns metadata including preview.

  @self.mcp.tool()
  def load_document(document_path: str, validation_level: str = "NORMAL") -> Dict[str, Any]:
      """Load a Markdown document from a file path (stateless only)."""
      try:
          validation_map = {
              "STRICT": ValidationLevel.STRICT,
              "NORMAL": ValidationLevel.NORMAL,
              "PERMISSIVE": ValidationLevel.PERMISSIVE
          }
          validation_enum = validation_map.get(validation_level.upper(), ValidationLevel.NORMAL)
          editor = self.processor.load_document(document_path, validation_enum)
          sections = editor.get_sections()
          content_preview = editor.to_markdown()[:200] + "..." if len(editor.to_markdown()) > 200 else editor.to_markdown()
          return {
              "success": True,
              "message": f"Successfully analyzed document at {document_path}",
              "document_path": document_path,
              "sections_count": len(sections),
              "content_preview": content_preview,
              "file_size": len(editor.to_markdown()),
              "stateless": True
          }
      except Exception as e:
          return self.processor.create_error_response(str(e), type(e).__name__)

• src/quantalogic_markdown_mcp/mcp_server.py:38-73 (handler)

  Base handler for the 'load_document' MCP tool. Decorated with @self.mcp.tool() for registration. Performs validation level mapping, loads via processor, and returns structured response with document analysis.

  @self.mcp.tool()
  def load_document(document_path: str, validation_level: str = "NORMAL") -> Dict[str, Any]:
      """
      Load and analyze a Markdown document from a file path.
      
      Args:
          document_path: Path to the Markdown file (supports absolute, relative, and ~ expansion)
          validation_level: Validation strictness - "STRICT", "NORMAL", or "PERMISSIVE"
      """
      try:
          # Convert string validation level to enum
          validation_map = {
              "STRICT": ValidationLevel.STRICT,
              "NORMAL": ValidationLevel.NORMAL,
              "PERMISSIVE": ValidationLevel.PERMISSIVE
          }
          validation_enum = validation_map.get(validation_level.upper(), ValidationLevel.NORMAL)
          
          # Load document without server state
          editor = self.processor.load_document(document_path, validation_enum)
          sections = editor.get_sections()
          content_preview = editor.to_markdown()[:200] + "..." if len(editor.to_markdown()) > 200 else editor.to_markdown()
          
          return {
              "success": True,
              "message": f"Successfully analyzed document at {document_path}",
              "document_path": document_path,
              "sections_count": len(sections),
              "content_preview": content_preview,
              "file_size": len(editor.to_markdown()),
              "stateless": True
          }
          
      except Exception as e:
          return self.processor.create_error_response(str(e), type(e).__name__)

• src/quantalogic_markdown_mcp/stateless_processor.py:58-83 (helper)

  Core helper function that implements document loading logic: path resolution, file validation, content reading with encoding fallback, and instantiation of SafeMarkdownEditor. Invoked by MCP tool handlers.

  def load_document(document_path: str, validation_level: ValidationLevel = ValidationLevel.NORMAL) -> SafeMarkdownEditor:
      """Load a document and create a SafeMarkdownEditor instance."""
      resolved_path = StatelessMarkdownProcessor.resolve_path(document_path)
      StatelessMarkdownProcessor.validate_file_path(resolved_path, must_exist=True, must_be_file=True)
      
      # Read the file content
      try:
          content = resolved_path.read_text(encoding='utf-8')
      except UnicodeDecodeError:
          # Try with different encodings
          for encoding in ['utf-8-sig', 'latin1', 'cp1252']:
              try:
                  content = resolved_path.read_text(encoding=encoding)
                  break
              except UnicodeDecodeError:
                  continue
          else:
              raise ValueError(f"Could not decode file {resolved_path} with any supported encoding")
      
      # Create editor instance
      editor = SafeMarkdownEditor(
          markdown_text=content,
          validation_level=validation_level
      )
      
      return editor