Skip to content
Back to search

mcp-server

Remote MCP server for passive subdomain discovery

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aditya-c7--mcp-server/badge.svg)](/listings/aditya-c7--mcp-server)

HTML

<a href="/listings/aditya-c7--mcp-server"><img src="/api/listings/aditya-c7--mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 146 lines
  1. <div align="center">
  2. # subdomain-index
  3. ### Read-only MCP server for indexed apex-domain names
  4. [![Public endpoint](https://img.shields.io/badge/Public_endpoint-server.adityahq.me-2563EB)](https://server.adityahq.me/mcp)
  5. [![Transport](https://img.shields.io/badge/Transport-Streamable_HTTP-0891B2)](#tool-contract)
  6. [![Deployment](https://img.shields.io/badge/Deployment-Cloudflare_Workers-F38020?logo=cloudflare&logoColor=white)](#deployment)
  7. </div>
  8. ## What it does
  9. Exposes one MCP tool, `list_subdomains`, which returns publicly indexed names for a single apex domain. No authentication. Results are lowercased, deduplicated, sorted, and capped at 100.
  10. ## Tool contract
  11. Input:
  12. | Field | Type | Required | Description |
  13. | --- | --- | --- | --- |
  14. | `domain` | `string` | yes | Single registrable apex domain, e.g. `example.com` |
  15. Response fields:
  16. | Field | Type | Description |
  17. | --- | --- | --- |
  18. | `domain` | `string` | Queried apex domain |
  19. | `count` | `number` | Names returned |
  20. | `total_seen` | `number` | Names found before truncation |
  21. | `truncated` | `boolean` | Whether results were capped |
  22. | `subdomains` | `string[]` | Indexed names, deduplicated and sorted |
  23. | `cached` | `boolean` | Whether the result came from cache |
  24. | `note` | `string` | Fixed disclaimer text |
  25. Description returned to clients:
  26. > List publicly indexed names for one apex domain.
  27. > Pass only the registrable apex, such as example.com or example.org.
  28. > Not a URL, not a subdomain, not an IP.
  29. > Results are indexed names only. Not a complete list.
  30. > Not checked for whether they are online.
  31. > On failure, say the lookup failed. Never invent names.
  32. Annotations: `readOnlyHint: true`, `openWorldHint: true`, `destructiveHint: false`.
  33. Example input:
  34. ```json
  35. { "domain": "example.com" }
  36. ```
  37. Example response:
  38. ```json
  39. {
  40. "domain": "example.com",
  41. "count": 4,
  42. "total_seen": 4,
  43. "truncated": false,
  44. "subdomains": [
  45. "api.example.com",
  46. "docs.example.com",
  47. "example.com",
  48. "www.example.com"
  49. ],
  50. "cached": false,
  51. "note": "Indexed names only. Not a complete list. Not checked if they are online."
  52. }
  53. ```
  54. ## How it works
  55. 1. Client sends a JSON-RPC request to `/mcp` over Streamable HTTP.
  56. 2. The handler validates the `Host` header against an allowlist.
  57. 3. Tool input is checked: only a single registrable apex domain is accepted.
  58. 4. Names are read from passive public data, then normalized, deduplicated, sorted, and capped.
  59. 5. Success returns a JSON-RPC tool result; failure returns `isError: true` with a plain message.
  60. Results are cached for 1 hour.
  61. `GET /health` returns `ok` (liveness only).
  62. ## Local development
  63. ```sh
  64. npm install
  65. npm run dev
  66. ```
  67. Local MCP endpoint: `http://localhost:8787/mcp`.
  68. MCP Inspector:
  69. ```sh
  70. npx @modelcontextprotocol/inspector@latest
  71. ```
  72. 1. Transport: Streamable HTTP.
  73. 2. URL: `http://localhost:8787/mcp`.
  74. 3. Connect, List tools: only `list_subdomains`; confirm its description and input schema match the contract above.
  75. 4. Call with `{"domain": "example.com"}`, then call again: the second result has `cached: true`.
  76. ## Verification
  77. ```sh
  78. npx tsc --noEmit
  79. node scripts/leak-scan.mjs
  80. node scripts/smoke.mjs # or: npm test
  81. ```
  82. For a warm cache, run with `SMOKE_EXPECT_MISS=0`. Point at production with `MCP_URL=https://server.adityahq.me`.
  83. ## Deployment
  84. Cloudflare Workers Git build on push to `main` deploys the `mcp-server` Worker that owns the custom domain. No local `wrangler deploy`.
  85. ## Configuration
  86. The Worker reads an optional runtime secret named `VT_API_KEY`. Set it as a Cloudflare Worker secret, in the dashboard under Secrets or with `wrangler secret put VT_API_KEY`. It is never committed to the repository. The server works without it.
  87. ## Tested
  88. - MCP Inspector GUI connected to `http://localhost:8787/mcp` and to `https://server.adityahq.me/mcp`. Both showed one tool, `list_subdomains`, and a successful call with a non-empty result.
  89. - Production cold lookup `cloudflare.com`: HTTP 200 in 1.4 s, `cached:false`, 100 returned names, `truncated:true`.
  90. - `aryanbudke.in`: 5 names returned in 703 ms (`cached:true`).
  91. - `xevrion.dev`: 14 names returned in 2.0 s (`cached:false`).
  92. - Local cold lookup `example.org`: 100 names in 950 ms (`cached:false`).
  93. - `node scripts/smoke.mjs`: local SMOKE PASS (49 checks, cold cache) — health, initialize, `tools/list`, `cached: false` then `cached: true`, rejection cases, leading-`www` exception. Production SMOKE PASS (48 checks, warm cache; `SMOKE_EXPECT_MISS=0`).
  94. - `npx tsc --noEmit`: exit 0.
  95. - `node scripts/leak-scan.mjs`: LEAK SCAN PASS.
  96. ## Not tested / user steps
  97. The client connection steps below are provided as user steps only. They have not been tested by the author and must not be claimed as working:
  98. - Claude: Settings -> Connectors -> Add custom connector -> enter the remote URL -> no sign-in. Free plan allows one custom connector.
  99. - Perplexity: Settings or Plugins -> add a custom MCP connector -> Streamable HTTP -> authentication none. If the control is missing, the plan does not include it; do not fake success.
  100. - ChatGPT web: Plugins -> add a custom MCP server -> server URL -> no authentication -> create as a plugin -> then @ it. If the menu is missing, report BLOCKED BY PLAN. Do not add OAuth to force it.
  101. ## Demo prompt
  102. ```
  103. Use list_subdomains on example.com. Return the tool result only. Do not guess extra names.
  104. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.