defuddle-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Defuddle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# defuddle-mcp
+
+[![npm version](https://img.shields.io/npm/v/defuddle-mcp.svg)](https://www.npmjs.com/package/defuddle-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/defuddle-mcp.svg)](https://www.npmjs.com/package/defuddle-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that extracts clean article content from web pages, removing clutter like ads, sidebars, and navigation elements.
+
+## Features
+
+- 🧹 **Clean Content Extraction** - Removes ads, sidebars, and other distractions
+- 📝 **Markdown Output** - Returns content in clean Markdown format with frontmatter
+- 🚀 **Zero Dependencies** - Built with Node.js built-ins only
+- ⚡ **Fast & Lightweight** - Minimal overhead, quick startup
+
+## Requirements
+
+- Node.js >= 18 (for built-in `fetch` support)
+
+## Installation
+
+### Install from npm
+
+```bash
+npm install -g defuddle-mcp
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/ryanxili/defuddle-mcp.git
+cd defuddle-mcp
+npm install -g .
+```
+
+## Usage
+
+### As a Global CLI Tool
+
+```bash
+defuddle-mcp
+```
+
+### With MCP Host (e.g., Claude Desktop)
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "defuddle": {
+      "command": "npx",
+      "args": ["-y", "defuddle-mcp"]
+    }
+  }
+}
+```
+
+Or with global install:
+
+```json
+{
+  "mcpServers": {
+    "defuddle": {
+      "command": "defuddle-mcp"
+    }
+  }
+}
+```
+
+### Programmatically
+
+```bash
+node index.js
+```
+
+The server runs on stdio and communicates via JSON-RPC 2.0.
+
+## Tool: defuddle
+
+Extract clean article content from a web page.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `url` | string | The URL of the web page to extract content from (required) |
+
+### Example Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "defuddle",
+    "arguments": {
+      "url": "https://example.com/article"
+    }
+  }
+}
+```
+
+### Example Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "---\ntitle: Example Article\nsource: https://example.com/article\nlanguage: en\nword_count: 1234\n---\n\n# Article Content\n\n..."
+      }
+    ]
+  }
+}
+```
+
+## API Reference
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize` | Initialize the MCP session |
+| `tools/list` | List available tools |
+| `tools/call` | Call a specific tool |
+
+### Error Codes
+
+| Code | Message | Description |
+|------|---------|-------------|
+| -32700 | Parse error | Invalid JSON received |
+| -32601 | Method not found | Requested method does not exist |
+
+## License
+
+MIT © [Defuddle](https://github.com/ryanxili/defuddle-mcp)
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
+- [defuddle.md](https://defuddle.md/) - Content extraction API used by this server

package/index.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Defuddle MCP Server
+ *
+ * An MCP (Model Context Protocol) server that extracts clean article content
+ * from web pages. Uses the defuddle.md API to remove ads, sidebars, and other
+ * clutter, returning content in Markdown format.
+ *
+ * @see https://modelcontextprotocol.io/
+ */
+
+const readline = require('readline');
+
+/**
+ * Create readline interface to read MCP requests from stdin.
+ * terminal: false enables stream mode for data processing instead of interactive terminal.
+ */
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+/**
+ * Handle each line of input (one JSON-RPC request).
+ * MCP protocol is based on JSON-RPC 2.0, with one complete JSON object per line.
+ */
+rl.on('line', async (line) => {
+  try {
+    // Parse JSON-RPC request
+    const request = JSON.parse(line.trim());
+
+    // ==================== Handle initialize Request ====================
+    // Client sends initialize first after connection to negotiate protocol version and capabilities
+    if (request.method === 'initialize') {
+      const response = {
+        jsonrpc: '2.0',
+        id: request.id,
+        result: {
+          // MCP protocol version
+          protocolVersion: '2026-03-14',
+          // Server capabilities declaration
+          capabilities: {
+            tools: {
+              // listChanged: true indicates support for tools/listChanged notifications
+              listChanged: false
+            }
+          },
+          // Server information
+          serverInfo: {
+            name: 'defuddle-mcp',
+            version: '1.0.0'
+          }
+        }
+      };
+      console.log(JSON.stringify(response));
+    }
+    // ==================== Handle tools/list Request ====================
+    // Client queries the list of tools provided by the server
+    else if (request.method === 'tools/list') {
+      const response = {
+        jsonrpc: '2.0',
+        id: request.id,
+        result: {
+          tools: [
+            {
+              // Tool name
+              name: 'defuddle',
+              // Tool description
+              description: 'Extract clean article content from a web page, removing clutter like ads and sidebars.',
+              // Input parameter schema (JSON Schema)
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  url: {
+                    type: 'string',
+                    description: 'The URL of the web page to extract content from.',
+                  },
+                },
+                // Required parameters
+                required: ['url'],
+              },
+            },
+          ],
+        },
+      };
+      console.log(JSON.stringify(response));
+    }
+    // ==================== Handle tools/call Request ====================
+    // Client invokes a specified tool
+    else if (request.method === 'tools/call') {
+      const { name, arguments: args } = request.params;
+      
+      if (name === 'defuddle') {
+        try {
+          // Call defuddle.md API to extract clean content
+          const response = await fetch(`https://defuddle.md/${encodeURIComponent(args.url)}`);
+          if (!response.ok) {
+            throw new Error(`Failed to fetch content: ${response.status} ${response.statusText}`);
+          }
+          // API returns Markdown format
+          const markdown = await response.text();
+          
+          // Build success response
+          const result = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              content: [
+                {
+                  type: 'text',
+                  text: markdown,
+                },
+              ],
+            },
+          };
+          console.log(JSON.stringify(result));
+        } catch (error) {
+          // Build error response (isError: true indicates tool execution failure)
+          const result = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              content: [
+                {
+                  type: 'text',
+                  text: `Error extracting content: ${error.message}`,
+                },
+              ],
+              isError: true,
+            },
+          };
+          console.log(JSON.stringify(result));
+        }
+      } else {
+        // Tool not found, return method not found error
+        const result = {
+          jsonrpc: '2.0',
+          id: request.id,
+          error: {
+            code: -32601,  // JSON-RPC 2.0 standard error code: Method not found
+            message: 'Method not found',
+          },
+        };
+        console.log(JSON.stringify(result));
+      }
+    }
+    // ==================== Unknown Method ====================
+    else {
+      const response = {
+        jsonrpc: '2.0',
+        id: request.id,
+        error: {
+          code: -32601,
+          message: 'Method not found',
+        },
+      };
+      console.log(JSON.stringify(response));
+    }
+  } catch (error) {
+    // ==================== JSON Parse Error ====================
+    // JSON-RPC 2.0 error code -32700 indicates Parse error
+    const response = {
+      jsonrpc: '2.0',
+      id: null,  // Cannot get request ID when parsing fails
+      error: {
+        code: -32700,
+        message: 'Parse error',
+      },
+    };
+    console.log(JSON.stringify(response));
+  }
+});
+
+// Server startup message output to stderr to avoid interfering with stdout JSON-RPC communication
+console.error('Defuddle MCP server running on stdio');

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "defuddle-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for extracting clean article content from web pages",
+  "main": "index.js",
+  "bin": {
+    "defuddle-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanxili/defuddle-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "defuddle",
+    "content-extraction",
+    "readability",
+    "web-scraper"
+  ],
+  "author": "ryanxili",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ]
+}