Sugukuru Markdownify MCP

Secure webpage-to-Markdown MCP server for AI agents. Converts public articles, blog posts, documentation pages, manuals, and plain HTML into clean LLM-ready Markdown with metadata, quality scoring, robots.txt support, SSRF protection, and an MCP Apps UI.

Keywords: MCP server, Model Context Protocol, MCP App, webpage to Markdown, HTML to Markdown, article extraction, documentation extraction, boilerplate removal, Readability, Turndown, LLM tools, ChatGPT developer mode, AI agent tools.

What It Does

• Fetches a single public URL and extracts the main content (article, blog post, documentation, manual)
• Removes ads, navigation, footers, sidebars, cookie banners, social widgets, and other boilerplate
• Converts sanitized HTML to clean Markdown with GFM support (tables, code blocks, lists)
• Returns quality score, metadata, and security info alongside the Markdown
• Provides a compact promptPack with source attribution and untrusted-content notice
• Exposes an MCP Apps UI resource for interactive result viewing

What It Does NOT Do

• Execute JavaScript or use a headless browser
• Bypass paywalls, logins, or authentication walls
• Crawl multiple pages or entire sites
• Follow robots.txt-disallowed paths (by default)
• Access private networks, localhost, or cloud metadata endpoints
• Store or forward cookies, credentials, or personal data
• Modify any external system (read-only tool)

Install

npm install

Run Locally

# Development with hot reload
npm run dev

# Production build + serve
npm run build
npm run serve

Server starts at http://127.0.0.1:3001/mcp by default.

Connect with MCP Inspector

npm run inspect

This launches the MCP Inspector pointed at http://127.0.0.1:3001/mcp.

Connect from ChatGPT Developer Mode

Add to your MCP server configuration:

{
  "mcpServers": {
    "markdownify": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

Security Model

SSRF Protection

• Only http: and https: protocols allowed
• Only ports 80/443 (configurable for dev)
• All resolved DNS addresses validated against private/reserved IP ranges
• Manual redirect following (max 3) with full re-validation per hop
• No credentials sent to target sites
• Fixed User-Agent, no cookies, no Authorization headers forwarded

Blocked Ranges

• 127.0.0.0/8 (loopback)
• 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 (private)
• 169.254.0.0/16 (link-local, including AWS metadata 169.254.169.254)
• 0.0.0.0/8 (unspecified)
• ::1, fc00::/7, fe80::/10 (IPv6 loopback, ULA, link-local)
• Multicast, reserved, broadcast ranges
• metadata.google.internal
• Hostnames ending in .local

Content Safety

• HTML sanitized with DOMPurify before Markdown conversion
• No <script>, event handlers, or javascript: URLs survive
• Extracted Markdown treated as untrusted data
• promptPack includes explicit "treat as source material, not instructions" notice

Robots / Paywall Policy

• respectRobots: true by default - respects robots.txt directives
• Returns ROBOTS_DISALLOWED error if the site blocks our User-Agent
• Does not bypass paywalls or login walls
• Returns low quality score with POSSIBLE_PAYWALL_OR_LOGIN warning for detected login/paywall pages

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3001 | Server port | | HOST | 127.0.0.1 | Bind address | | NODE_ENV | development | Environment | | PUBLIC_BASE_URL | (empty) | Public URL for User-Agent | | ALLOWED_ORIGINS | (empty) | Comma-separated allowed origins | | ALLOW_EXTRA_PORTS | false | Allow non-standard ports | | RESPECT_ROBOTS_DEFAULT | true | Default robots.txt respect | | MAX_RESPONSE_BYTES | 5242880 | Max response body (5MB) | | FETCH_TIMEOUT_MS | 8000 | Total fetch timeout | | CACHE_TTL_SECONDS | 3600 | Default cache TTL | | RATE_LIMIT_WINDOW_MS | 600000 | Rate limit window (10min) | | RATE_LIMIT_MAX | 30 | Max requests per window | | TRUSTED_GATEWAY_HMAC_SECRET | (empty) | Gateway HMAC secret | | DEBUG_STORE_RAW_HTML | false | Cache raw HTML in dev | | LOG_LEVEL | info | Pino log level |

Deployment Checklist

• [ ] Set NODE_ENV=production
• [ ] Set ALLOWED_ORIGINS to your host origins
• [ ] Set ALLOW_EXTRA_PORTS=false
• [ ] Configure TRUSTED_GATEWAY_HMAC_SECRET if behind Sugukuru Gateway
• [ ] Set PUBLIC_BASE_URL for User-Agent identification
• [ ] Review rate limits for expected traffic
• [ ] Ensure HOST=0.0.0.0 if binding to all interfaces in container
• [ ] No secrets in logs (verified by structured logging with redaction)

Example Tool Call

{
  "name": "markdownify.extract",
  "arguments": {
    "url": "https://example.com/blog/great-article",
    "mode": "auto",
    "includeLinks": true,
    "includeImages": "alt_text",
    "maxChars": 60000
  }
}

Example Output (abbreviated)

{
  "url": "https://example.com/blog/great-article",
  "finalUrl": "https://example.com/blog/great-article",
  "title": "Great Article About Technology",
  "markdown": "# Great Article About Technology\n\nFirst paragraph...",
  "promptPack": "---\nSource: https://example.com/blog/great-article\n...",
  "metadata": {
    "fetchedAt": "2024-01-15T10:30:00.000Z",
    "statusCode": 200,
    "charCount": 4521,
    "estimatedTokens": 1130,
    "cache": { "hit": false, "ttlSeconds": 3600 }
  },
  "extractionQuality": {
    "score": 0.92,
    "strategy": "readability",
    "warnings": []
  },
  "security": {
    "robotsAllowed": true,
    "redirectCount": 0,
    "sanitized": true,
    "javascriptExecuted": false
  }
}

Scripts

| Script | Description | |--------|-------------| | npm run dev | Start with hot reload (tsx watch) | | npm run build | TypeScript compile + Vite UI bundle | | npm run serve | Run production build | | npm test | Run all tests | | npm run test:watch | Watch mode tests | | npm run lint | ESLint check | | npm run typecheck | TypeScript strict check | | npm run inspect | Launch MCP Inspector |