markitdown-mcp AGENTS.md

AI Agents Integration Guide

This guide provides comprehensive information for AI agents and assistants on how to effectively use the MarkItDown MCP server for document conversion tasks.

🤖 Quick Reference for AI Agents

Primary Use Cases

• Convert documents (PDF, Word, Excel, PowerPoint) to markdown
• Extract readable text from various file formats
• Batch process directories of documents
• Support users with document analysis workflows

Available Tools

1. convert_file - Convert individual files
2. convert_directory - Batch convert directories
3. list_supported_formats - Show supported formats

🛠️ Tool Usage Guide

convert_file Tool

When to use:

• User provides a file path for conversion
• User shares base64 content that needs conversion
• Single document analysis required

Parameters:

{
  "file_path": "/path/to/document.pdf",     // For local files
  "file_content": "base64encoded...",      // For shared content
  "filename": "document.pdf"               // Required with file_content
}

Example scenarios:

• "Convert this PDF to markdown"
• "Extract text from this Word document"
• "Make this Excel file readable"

convert_directory Tool

When to use:

• User wants to process multiple files
• Batch conversion workflows
• Directory cleanup/organization tasks

Parameters:

{
  "input_directory": "/path/to/input",
  "output_directory": "/path/to/output"    // Optional
}

Example scenarios:

• "Convert all documents in this folder"
• "Process my downloads directory"
• "Batch convert these reports"

list_supported_formats Tool

When to use:

• User asks about supported file types
• Error troubleshooting (unsupported format)
• Capability discovery

Parameters: None

Example scenarios:

• "What file types can you convert?"
• "Can you handle PowerPoint files?"
• "Is Excel supported?"

💡 Best Practices for AI Agents

1. Format Detection

# Always check format support first if unsure
if user_asks_about_unknown_format:
    call_tool("list_supported_formats")