# pleamo MCP server

Exposes pleamo's AI scam/phishing URL checks as **MCP tools**, so any MCP client
(Claude Desktop, Cursor, your own agent) can ask pleamo "is this link safe?"
before opening or recommending it.

It's a thin, authenticated proxy to the hosted pleamo API — every check goes
through the same per-user and global caps that protect the service.

## Tools

| Tool | What it does |
| --- | --- |
| `check_url` | Judge a URL: verdict (safe/suspicious/dangerous), severity, confidence, reason |
| `report_false_positive` | Flag a wrongly-blocked domain for review |
| `get_status` | Your plan + today's AI-check usage |

## Setup

1. Get a **pleamo API key** (a revocable key from the dashboard at
   `https://dash.pleamo.app/keys`).
2. Point your MCP client at this server. For **Claude Desktop**, add to
   `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pleamo": {
      "command": "npx",
      "args": ["-y", "pleamo-mcp"],
      "env": {
        "PLEAMO_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

Restart the client. You'll then be able to say things like *"check this link with
pleamo: https://paypa1-login.example"* and the agent will call `check_url`.

### Environment

| Var | Default | Notes |
| --- | --- | --- |
| `PLEAMO_TOKEN` | — | Required. Bearer token for the pleamo API. |
| `PLEAMO_API_BASE` | `https://dash.pleamo.app` | Override for local dev (e.g. `http://localhost:4400`). |

## Develop

```bash
npm install
npm run verify   # lint + format + unit tests
npm start        # runs the stdio server (expects an MCP client on stdin)
```

Quick stdio smoke test (lists the tools):

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node src/server.js
```

## Remote (hosted) alternative

If your client supports **remote MCP servers**, you don't need this local process
at all — connect straight to the hosted endpoint:

```
https://dash.pleamo.app/api/mcp
```

It speaks JSON-RPC over HTTP (same three tools) and authenticates with a pleamo
**API key** as a Bearer token. Create a revocable key at
`https://dash.pleamo.app/keys`. This local stdio server is for clients that only
speak stdio (e.g. current Claude Desktop).

## Notes

- **Auth / tokens** — get a revocable **API key** from the dashboard (`/keys`)
  and set it as `PLEAMO_TOKEN`. (A raw session token also works, but keys are
  the right, revocable option.)
- **Transport** — this package is stdio; the hosted `/api/mcp` above is the
  remote Streamable-HTTP variant.
- **The other MCP direction** — letting the *extension* route checks through the
  user's own agent (BYO-via-MCP) is tracked alongside the extension source at
  [pleamo/pleamo-chrome-extension](https://github.com/pleamo/pleamo-chrome-extension).