OfficeReader-MCP

Instructions

Implementation Reference

• src/officereader_mcp/server.py:177-221 (handler)

  The main handler for the 'convert_document' tool within the @server.call_tool() function. It validates input parameters, calls OfficeConverter.convert_file(), processes the result, and returns a JSON summary with paths and preview.
  async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]: """Handle tool calls.""" try: converter = get_converter() cache_notice = get_cache_location_notice(converter) if name == "convert_document": file_path = arguments.get("file_path") if not file_path: return [TextContent( type="text", text=json.dumps({"error": "file_path is required"}, ensure_ascii=False) )] extract_images = arguments.get("extract_images", True) image_format = arguments.get("image_format", "file") output_name = arguments.get("output_name") result = converter.convert_file( file_path=file_path, extract_images=extract_images, image_format=image_format, output_name=output_name, ) # Return summary with markdown preview response = { "status": "success", "file_type": result.get("file_type", "unknown"), "cache_location": str(converter.cache_dir), "output_path": result["output_path"], "conversion_dir": result["conversion_dir"], "images_extracted": len(result["images"]), "image_paths": result["images"], "metadata": result["metadata"], "markdown_preview": result["markdown"][:2000] + "..." if len(result["markdown"]) > 2000 else result["markdown"], "markdown_length": len(result["markdown"]), "hint": "Use 'list_conversions' to see all cached files, or 'read_converted_markdown' to read the full content.", } return [TextContent( type="text", text=f"{cache_notice}\n\n" + json.dumps(response, ensure_ascii=False, indent=2) )]
• src/officereader_mcp/server.py:57-99 (schema)

  Input schema and description for the 'convert_document' tool, defining parameters like file_path, extract_images, image_format, and output_name.
  Tool( name="convert_document", description=f"""Convert Office documents to Markdown format for Claude to read. Supported formats: - Word: .docx, .doc - Excel: .xlsx, .xls (converts each sheet to a Markdown table) - PowerPoint: .pptx, .ppt (extracts text and images from slides) Features: - Text extraction with formatting (headings, bold, italic, lists, tables) - Image extraction and optimization (auto-compressed for efficiency) - Speaker notes extraction from PowerPoint - Multi-sheet support for Excel Images are automatically optimized (WebP format, max 1920x1080) to reduce size while maintaining readability for Claude.""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, "extract_images": { "type": "boolean", "description": "Whether to extract and include images (default: true)", "default": True, }, "image_format": { "type": "string", "enum": ["file", "base64", "both"], "description": "How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both", "default": "file", }, "output_name": { "type": "string", "description": "Custom name for the output (without extension). If not provided, generates from filename.", }, }, "required": ["file_path"], }, ),
• src/officereader_mcp/server.py:51-168 (registration)

  Registration of all tools including 'convert_document' via the @server.list_tools() decorator in the MCP server.
  @server.list_tools() async def list_tools() -> list[Tool]: """List available tools for the MCP server.""" supported_exts = ", ".join(get_supported_extensions()) return [ Tool( name="convert_document", description=f"""Convert Office documents to Markdown format for Claude to read. Supported formats: - Word: .docx, .doc - Excel: .xlsx, .xls (converts each sheet to a Markdown table) - PowerPoint: .pptx, .ppt (extracts text and images from slides) Features: - Text extraction with formatting (headings, bold, italic, lists, tables) - Image extraction and optimization (auto-compressed for efficiency) - Speaker notes extraction from PowerPoint - Multi-sheet support for Excel Images are automatically optimized (WebP format, max 1920x1080) to reduce size while maintaining readability for Claude.""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, "extract_images": { "type": "boolean", "description": "Whether to extract and include images (default: true)", "default": True, }, "image_format": { "type": "string", "enum": ["file", "base64", "both"], "description": "How to handle images: 'file' saves to disk (recommended), 'base64' embeds in markdown, 'both' does both", "default": "file", }, "output_name": { "type": "string", "description": "Custom name for the output (without extension). If not provided, generates from filename.", }, }, "required": ["file_path"], }, ), Tool( name="read_converted_markdown", description="""Read the content of a previously converted markdown file. Use this after convert_document to get the actual markdown content. This is useful when you want to process or analyze the converted document.""", inputSchema={ "type": "object", "properties": { "markdown_path": { "type": "string", "description": "Path to the markdown file (returned by convert_document)", }, }, "required": ["markdown_path"], }, ), Tool( name="list_conversions", description="""List all cached document conversions. Shows all documents that have been converted, including their output paths and number of extracted images. Useful for finding previously converted files.""", inputSchema={ "type": "object", "properties": {}, }, ), Tool( name="clear_cache", description="""Clear all cached conversions. Removes all converted markdown files and extracted images from the cache. Use this to free up disk space or reset the conversion cache.""", inputSchema={ "type": "object", "properties": {}, }, ), Tool( name="get_document_metadata", description=f"""Get metadata from an Office document without full conversion. Extracts document properties like title, author, creation date, etc. Faster than full conversion when you only need metadata. Supported formats: {supported_exts}""", inputSchema={ "type": "object", "properties": { "file_path": { "type": "string", "description": f"Absolute path to the Office document. Supported: {supported_exts}", }, }, "required": ["file_path"], }, ), Tool( name="get_supported_formats", description="""Get list of all supported file formats. Returns a dictionary of file types (word, excel, powerpoint) and their extensions.""", inputSchema={ "type": "object", "properties": {}, }, ), ]
• src/officereader_mcp/converter.py:575-659 (helper)

  Core helper method OfficeConverter.convert_file() called by the handler. Detects document type and delegates to specialized converters (word, excel, powerpoint) for the actual conversion logic.
  self, file_path: str, extract_images: bool = True, image_format: str = "file", output_name: Optional[str] = None, ) -> dict: """ Convert any supported Office document to Markdown. Args: file_path: Path to the document extract_images: Whether to extract images image_format: "file", "base64", or "both" output_name: Custom output name Returns: dict with markdown, images, metadata, and paths """ file_path = Path(file_path) if not file_path.exists(): raise FileNotFoundError(f"File not found: {file_path}") file_type = get_file_type(file_path) if file_type is None: supported = [] for exts in SUPPORTED_FORMATS.values(): supported.extend(exts) raise ValueError( f"Unsupported file format: {file_path.suffix}. " f"Supported formats: {', '.join(supported)}" ) # Generate output name if not output_name: file_hash = self._get_file_hash(file_path) output_name = f"{file_path.stem}_{file_hash[:8]}" # Create output directory conversion_dir = self.output_dir / output_name conversion_dir.mkdir(exist_ok=True) images_dir = conversion_dir / "images" images_dir.mkdir(exist_ok=True) # Convert based on file type if file_type == "word": result = self._docx_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, ) elif file_type == "excel": result = self.excel_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, conversion_dir=conversion_dir, images_dir=images_dir, ) elif file_type == "powerpoint": result = self.pptx_converter.convert_file( str(file_path), extract_images=extract_images, image_format=image_format, output_name=output_name, conversion_dir=conversion_dir, images_dir=images_dir, ) else: raise ValueError(f"Unknown file type: {file_type}") # Save markdown if not already saved (for Excel/PPT) md_path = conversion_dir / f"{output_name}.md" if "output_path" not in result: with open(md_path, "w", encoding="utf-8") as f: f.write(result["markdown"]) result["output_path"] = str(md_path) result["conversion_dir"] = str(conversion_dir) # Add file type info result["file_type"] = file_type return result