# Defuddle MCP Server

A thin MCP wrapper around the [Obsidian](https://obsidian.md/) team's [Defuddle](https://github.com/obsidian-tasks/defuddle) tool. It fetches a webpage and returns clean, structured Markdown with metadata (title, author, publish date, description, domain, word count).

## What it does

- Exposes one MCP tool: `webpage_to_markdown`
- Converts webpages into focused Markdown, stripping ads, navigation, and other clutter.
- Returns both plain Markdown text and structured metadata.
- Requires Bearer-token authorization on every HTTP endpoint.

## Endpoints

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/mcp`   | POST   | Bearer token | MCP tool calls |
| `/health`| GET    | Bearer token | Health check |

Default listening port is `3000` inside the container. The included `docker-compose.yml` exposes it on host port `3007`.

## Quick start

### With Docker Compose

1. Copy the example environment file and set a real token:

   ```bash
   cp .env.example .env
   # edit .env
   # DEFUDDLE_MCP_TOKEN=your-secret-bearer-token
   ```

2. Build and run:

   ```bash
   docker compose up --build -d
   ```

3. The server is now available at `http://localhost:3007/mcp`.

### Locally with Node.js

1. Install dependencies and build:

   ```bash
   npm install
   npm run build
   ```

2. Set the required token:

   ```bash
   export DEFUDDLE_MCP_TOKEN=your-secret-bearer-token
   # optional: export PORT=4000
   ```

3. Start the server:

   ```bash
   npm start
   ```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `DEFUDDLE_MCP_TOKEN` | *(required)* | Bearer token clients must send as `Authorization: Bearer <token>` |
| `PORT` | `3000` | Port the server listens on inside the container |

To use a custom port, set both `PORT` and adjust the Docker Compose port mapping, e.g.:

```yaml
ports:
  - "4000:4000"
```

## Connect an MCP client

Add a server config like this (example for a client that supports streamable HTTP):

```json
{
  "mcpServers": {
    "defuddle": {
      "url": "http://localhost:3007/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-bearer-token"
      }
    }
  }
}
```

## Development

- `npm run dev` — run directly from TypeScript.
- `npm run build` — compile to `dist/`.