# DonDominio MCP Server

An **unofficial** [MCP](https://modelcontextprotocol.io) server that exposes the
entire **DonDominio / MrDomain** reseller API as **106** LLM-callable tools.
Manage domains, hosting, SSL certificates, and external users from Claude,
Cursor, Cline, Codex, Hermes, or any MCP-compatible client.

> **Not affiliated with DonDominio / MrDomain.** Use at your own risk and respect
> the [usage policy](https://dondominio.dev/en/api/docs/usage-policy/).

---

## Quick start

```bash
git clone https://github.com/ec-dev0/don-dominio-mcp
cd don-dominio-mcp
npm install && npm run build
cp .env.example .env        # set DONDOMINIO_API_USER / DONDOMINIO_API_PASS
node dist/index.js          # stdio mode
```

## Install from GitHub (npx)

Point any MCP client at the repo; `npx` clones, builds, and runs it for you:

```json
{
  "mcpServers": {
    "don-dominio": {
      "command": "npx",
      "args": ["-y", "github:ec-dev0/don-dominio-mcp"],
      "env": {
        "DONDOMINIO_API_USER": "your_api_user",
        "DONDOMINIO_API_PASS": "your_api_password"
      }
    }
  }
}
```

> When launched by a client via `npx`, `.env` files are **not** read — pass
> credentials only through the config's `env` block.

## Requirements

- **Node.js ≥ 20**.
- A DonDominio / MrDomain account with **API access enabled**
  ([request it here](https://www.mrdomain.com/en/resellers/api/#requestaccess)).
- The caller's **public IP** must be whitelisted in the DonDominio panel. Check
  the IP DonDominio sees with `dondominio_tool_hello` or `dondominio_account_info`.

## Configuration

| Variable              | Default                          | Description                                                              |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| `DONDOMINIO_API_USER` | _(required)_                     | DonDominio API username.                                                 |
| `DONDOMINIO_API_PASS` | _(required)_                     | DonDominio API password.                                                 |
| `TRANSPORT`           | `stdio`                          | `stdio` or `http`.                                                       |
| `PORT`                | `3000`                           | HTTP port (only with `TRANSPORT=http`).                                  |
| `ALLOWED_HOSTS`       | `localhost,127.0.0.1,[::1]`       | Allowed hosts (DNS-rebinding protection).                                |
| `ALLOWED_ORIGINS`     | `localhost,127.0.0.1`             | Allowed `Origin` headers.                                                |
| `MCP_AUTH_TOKEN`      | _(unset)_                        | If set, `/mcp` requires `Authorization: Bearer <token>`.                 |
| `MCP_MAX_CONCURRENT`  | `3`                              | Max concurrent requests per IP (→ 429). Matches DonDominio's usage policy (3 connections per IP). |
| `DEBUG`               | `1` to enable                    | Diagnostic output to `stderr`.                                           |

## Usage

```bash
# stdio (default) – for local agents
DONDOMINIO_API_USER=... DONDOMINIO_API_PASS=... node dist/index.js

# HTTP – for remote agents (http://localhost:3000/mcp)
TRANSPORT=http PORT=3000 DONDOMINIO_API_USER=... DONDOMINIO_API_PASS=... node dist/index.js
```

### Inspector (interactive debugger)

```bash
npm run inspect   # npx @modelcontextprotocol/inspector dist/index.js
```

Opens a web UI to explore all 106 tools, their schemas, and test them risk-free.

## Available tools

| Module     | Tools | What it lets you do                                                |
| ---------- | ----- | ------------------------------------------------------------------ |
| `tool/`    | 6     | Hello, IDN/Punycode, domain suggest, ISO tables, DIG, zone-check.  |
| `account/` | 3     | Info & balance, promotions, TLD catalogue with prices.               |
| `domain/`  | 24    | Check, register, transfer, renew, NS, contacts, DNSSEC…             |
| `contact/` | 4     | Reusable WHOIS contact templates.                                  |
| `service/` | 47    | Hosting: FTP, databases, subdomains, redirects, mail, DNS.         |
| `ssl/`     | 13    | CSR, products, certificate lifecycle, validation, SAN.             |
| `user/`    | 9     | External panel users and per-domain permissions.                    |

## Examples

- *"Is `example.es` available?"* → `dondominio_domain_check`
- *"Convert `año.es` to Punycode."* → `dondominio_tool_idn_converter`
- *"List my .com domains."* → `dondominio_domain_list`
- *"Create mailbox `info@mydomain.com` on service `srv-mydomain`."* → `dondominio_service_mail_create`

> Do not loop on `dondominio_domain_check` or `dondominio_tool_domain_suggests`;
> DonDominio bans accounts for mass availability checks.

## Security

- All calls go over HTTPS to `https://simple-api.dondominio.net/`.
- Hardened HTTP transport: Host/Origin validation, optional Bearer auth, and a
  per-IP concurrency cap.
- Tools declare honest annotations for the LLM (`readOnlyHint`,
  `destructiveHint`, `idempotentHint`, `openWorldHint`).

## Troubleshooting

| Symptom                                     | Cause / fix                                                                 |
| ------------------------------------------- | ---------------------------------------------------------------------------- |
| Error `100` when calling a tool              | Invalid credentials or IP not whitelisted.                                 |
| Error `12`                                  | Your IP is not whitelisted with DonDominio.                                 |
| Client disconnects at startup               | No logs on `stdout` by default; use `DEBUG=1` for stderr diagnostics.       |
| HTTP 401                                    | Missing `Authorization: Bearer <MCP_AUTH_TOKEN>`.                            |
| HTTP 429                                    | Too many concurrent requests from one IP; wait or raise `MCP_MAX_CONCURRENT`. |

## Development

```bash
npm install
npm run dev         # tsx watch (hot reload)
npm run build       # tsc → dist/
npm run inspect     # MCP Inspector
npm run clean       # rm -rf dist
```

Code structure and conventions live in [`AGENTS.md`](./AGENTS.md).

## Links

- DonDominio API docs: <https://dondominio.dev/en/api/docs/api/>
- Usage policy: <https://dondominio.dev/en/api/docs/usage-policy/>
- MCP specification: <https://modelcontextprotocol.io>

## License

MIT — see [`LICENSE`](./LICENSE).