# EDF MCP — Expired Domain Finder

[![Tests](https://github.com/MuhammdQasim/edf-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/MuhammdQasim/edf-mcp/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Use an MCP client such as Codex to control your locally installed **EDF – Expired Domain Finder**: check domains, discover external links, follow background jobs and export results.

This is an independent community bridge by **Muhammad Qasim**. You must obtain and install EDF separately from its creator. This repository does not contain EDF's executable, application archive, research datasets or API credentials, and does not modify the installed app. See [NOTICE.md](NOTICE.md).

> **Availability signals are provisional.** A DNS failure, WHOIS error or `candidate_available` result is not proof of expiry, registrar availability, valuable backlinks or permission to use a former brand. Confirm at a registrar before buying.

## What you need

- **Windows**, with EDF installed locally. The tested executable is `EDF - Expired Domain Finder.exe`.
- **Node.js 22 or later** ([official download](https://nodejs.org/en/download)).
- An MCP client that can launch a local **stdio** server.
- The [compatible EDF package](docs/COMPATIBILITY.md). Changed app packages are rejected until reviewed.

The 12 core EDF tools need **no API key**. The optional thirteenth tool uses your own Ahrefs public-endpoint key. Running the MCP is local; it is not a hosted HTTP endpoint for ChatGPT's cloud connector form.

## Install

Clone the repository, or download **Code → Download ZIP** and extract it to a permanent folder:

```powershell
git clone https://github.com/MuhammdQasim/edf-mcp.git C:\Tools\edf-mcp
cd C:\Tools\edf-mcp
npm.cmd ci
npm.cmd test
npm.cmd run verify
```

The tests and default verifier use isolated fixtures. They do not launch EDF, crawl a website, query WHOIS, spend Ahrefs quota or resume old jobs.

Check your actual installation without starting it:

```powershell
$env:EDF_INSTALL_DIR = 'D:\EDF 2.0'
npm.cmd run check-install
```

An installation path containing spaces is supported. Keep this folder in place after configuring your client. Do not point a new installation at another user's saved-job directory.

## Connect Codex

Merge the following into your user `~/.codex/config.toml`. On Windows, `~` means your user-profile folder. Edit the **absolute** Node, repository and EDF paths for your computer; do not overwrite your other MCP entries.

```toml
[mcp_servers.edf]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Tools\edf-mcp\src\server.mjs']
startup_timeout_sec = 20
tool_timeout_sec = 90

[mcp_servers.edf.env]
EDF_INSTALL_DIR = 'D:\EDF 2.0'
EDF_DATA_DIR = 'C:\Tools\edf-mcp\data'
```

Restart/reconnect the MCP client after changing its configuration. Start with this request:

> Use EDF to check its status. If the installed package is compatible and there is no manual work in progress, launch EDF for automation. Check example.com and example.org, wait for the job to finish, then export the results as CSV. Do not crawl any websites.

If EDF is already open without its automation connection, save and close that instance yourself before calling `edf_launch`. The bridge will not close your work. You can also start with `edf_status` only; it never launches the app.

The configuration is also available in [examples/codex.toml](examples/codex.toml). See [official Codex MCP documentation](https://developers.openai.com/codex/mcp).

## Other MCP clients

For clients using an `mcpServers` JSON configuration, adapt [examples/mcp-stdio.json](examples/mcp-stdio.json):

```json
{
  "mcpServers": {
    "edf": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Tools\\edf-mcp\\src\\server.mjs"],
      "env": {
        "EDF_INSTALL_DIR": "D:\\EDF 2.0",
        "EDF_DATA_DIR": "C:\\Tools\\edf-mcp\\data"
      }
    }
  }
}
```

Each client has its own configuration location and restart procedure. Use its documentation. These are standard stdio configuration examples; this release's protocol tests use the official MCP SDK and do not certify every client UI.

## Tools

| Tool | What it does |
| --- | --- |
| `edf_status` | Read installation, package hash, connection, manual activity and saved active jobs; no app launch |
| `edf_launch` | Start or reuse the verified app with a loopback automation connection |
| `edf_get_configuration` | Read native DNS/WHOIS settings, optionally for one TLD |
| `edf_dns_lookup` | Native batch A-record checks, up to 100 hostnames |
| `edf_whois_lookup` | Native WHOIS for one hostname, with optional raw response |
| `edf_check_domains` | Start a saved background check of up to 1,000 hostnames |
| `edf_crawl_site` | Start a bounded site/sitemap crawl and optional external-domain checks |
| `edf_list_jobs` | List saved jobs, including interrupted jobs |
| `edf_get_job` | Poll progress and read paginated/filterable results |
| `edf_cancel_job` | Stop new work; retain in-flight answers and partial results |
| `edf_export_results` | Write a CSV/JSON export inside the configured data folder |
| `edf_get_app_results` | Read manual EDF UI rows without replacing them |
| `edf_ahrefs_domain_rating` | Optional Ahrefs DR lookup for up to 1,000 public root domains |

### Check domains with seven workers

Tool name: `edf_check_domains`. Arguments:

```json
{
  "domains": ["example.com", "example.org", "example.net"],
  "mode": "dns_then_whois",
  "concurrency": 7,
  "delay_ms": 500
}
```

Use your own explicit target list. `dns_then_whois` performs one native DNS batch and WHOIS for names without an A record; `whois_all` requests WHOIS for every name. The default is seven checking workers; choose 1–7. WHOIS calls share one start gate, with a minimum configurable delay of 250 ms (default 500 ms). This overlaps slow responses without promising sevenfold speed. Respect registry quotas and increase spacing when needed.

The tool returns an ID such as `edf_...`. Pass that ID to `edf_get_job` until the state is `completed`, `cancelled`, `failed` or `interrupted`, then call `edf_export_results` with `format: "csv"` or `"json"`. See [the full workflow](docs/USAGE.md) for exact calls.

### Discover external links

Ask your MCP client:

> Use EDF to crawl https://example.com/ with max_pages 5, max_domains 25 and check_domains false. Poll the saved job and report discovered external hostnames. Do not start other crawls.

The built-in crawler is bounded to **500 pages and 1,000 external hostnames**. Its page queue stays on the seed origin. It uses the installed app's HTML extraction, does not render JavaScript, and inherits native redirect/sitemap behavior. It is not the separate full-site research pipeline and does not guarantee every live page was inspected. Its optional checking phase is sequential. See [limitations](docs/USAGE.md#crawler-limitations).

## Read the results correctly

| Status | Meaning |
| --- | --- |
| `dns_active` | An A record resolved; registration status was not independently established by that signal |
| `registered` | Usable native WHOIS evidence contained registration fields |
| `candidate_available` | Eligible root-domain WHOIS returned a no-match marker without registration fields |
| `unknown` | Empty, failed, rate-limited, unsupported or inconclusive lookup |

The Public Suffix List prevents subdomains, private-platform tenants and unknown suffixes from receiving a purchase-candidate label. Hostnames are preserved: `www.example.com` is not silently changed to `example.com`. Submit the exact root you want to check. A candidate is never automatically purchased.

## Saved jobs and configuration

By default, runtime files are stored in this repository's ignored `data/` folder:

```text
data/jobs/       durable job JSON
data/exports/    generated CSV/JSON
data/active.lock job-owner lock
data/launch.lock app-launch lock
```

`EDF_DATA_DIR` changes saved jobs/exports and their active-job lock. The app-launch lock remains under this checkout's `data/`, even when `EDF_DATA_DIR` is overridden. Use one checkout for one installed EDF app. Multiple clients sharing the same data folder serialize saved jobs; copying the server or choosing different data folders does not provide an app-wide lock. Do not run competing app instances or manual work alongside automated requests.

The server saves progress after completed answers. Closing the owning MCP process interrupts the job; the next startup preserves partial results and marks dead-owner work `interrupted`. It does not silently retry it. Cancellation must go through the connection that owns the active job.

| Environment variable | Default / purpose |
| --- | --- |
| `EDF_INSTALL_DIR` | `D:\EDF 2.0`; folder containing the executable and `resources/app.asar` |
| `EDF_DATA_DIR` | This checkout's `data/`; saved jobs and exports |
| `EDF_CDP_PORT` | `9335`; local automation port |
| `EDF_EXPECTED_ASAR_SHA256` | Reviewed package hash; see [compatibility](docs/COMPATIBILITY.md) before changing it |
| `AHREFS_API_KEY` | Optional process-environment credential; EDF tools do not need it |
| `AHREFS_API_KEY_PROTECTED_FILE` | Optional Windows DPAPI credential file; see [Ahrefs setup](docs/AHREFS.md) |

## Optional Ahrefs Domain Rating

The optional tool calls the fixed Ahrefs public endpoint using your own key, without launching EDF or creating a domain-check job. No key is included here. Availability, pricing/access and quotas are controlled by Ahrefs. [Setup and attribution requirements](docs/AHREFS.md).

**DR is not DA or PA**, and none of these scores proves backlink quality, traffic or registration availability. The tool does not provide Ubersuggest metrics, Wayback reviews or automatic registrar confirmation.

## Help and development

- [Step-by-step usage](docs/USAGE.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Supported package and updates](docs/COMPATIBILITY.md)
- [Testing and verification](docs/VERIFICATION.md)
- [Contributing](CONTRIBUTING.md) and [security reporting](SECURITY.md)

The **MIT license covers this original bridge only**. EDF and other third-party products retain their own licenses, branding and access requirements. Please do not upload credentials, raw WHOIS personal details, saved jobs or private research to issues.