vpndetection-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection MCP Server
+
+[![npm](https://img.shields.io/npm/v/vpndetection-mcp.svg)](https://www.npmjs.com/package/vpndetection-mcp)
+[![license](https://img.shields.io/npm/l/vpndetection-mcp.svg)](LICENSE)
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for the [VPNDetection](https://vpndetection.io) API.
+
+It gives an AI agent five read-only tools for anonymity detection: whether an address belongs to a VPN, a residential, datacenter or mobile proxy, a Tor node, a public relay, a hosting provider or a CDN, plus the catalogue of datasets your organisation is licensed to download.
+
+## Getting Started
+
+**No API key needed to start.** The free tier answers `ip` and `is_vpn`, and allows 1000 requests per day per source address.
+
+Add this to your MCP client's config:
+
+```json
+{
+  "mcpServers": {
+    "vpndetection": {
+      "command": "npx",
+      "args": ["-y", "vpndetection-mcp"]
+    }
+  }
+}
+```
+
+Then ask it something like *"is 45.83.91.1 a VPN?"*.
+
+Requires Node.js 22 or newer.
+
+### With an API key
+
+A key unlocks the provider name, the classification datasets and the proxy families. Put it in the environment:
+
+```json
+{
+  "mcpServers": {
+    "vpndetection": {
+      "command": "npx",
+      "args": ["-y", "vpndetection-mcp"],
+      "env": { "VPNDETECTION_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+`VPNDETECTION_BASE_URL` overrides the endpoint if you need to point somewhere else.
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `lookup_ip` | Classify one address. |
+| `lookup_ips` | Classify up to 100 addresses in one call, keyed by address. |
+| `list_databases` | The datasets your organisation is licensed for. |
+| `database_metadata` | A dataset's columns, sample rows, row count, build date and file sizes. |
+| `database_checksum` | The published digests for one dataset file. |
+
+Every tool is read-only. There is deliberately no download tool: the datasets run to several GB, which is not something an agent should pull into a conversation. Fetch them with the [client libraries](https://github.com/vpndetection-io) or the API instead.
+
+## Reading a result
+
+Each lookup comes back with a `coverage` block beside it:
+
+```json
+{
+  "result": { "ip": "45.83.91.1", "is_vpn": true },
+  "coverage": {
+    "included": ["ip", "is_vpn"],
+    "not_included": ["is_hosting", "is_tor", "hosting", "tor", "..."],
+    "note": "The fields in not_included were not returned, because this API key's plan does not include them. ..."
+  }
+}
+```
+
+This matters more here than in a normal client library. A field missing from a result means your plan doesn't include it, never "we checked and found nothing" - and a model reading the result on its own will otherwise treat the absence as a negative answer. `coverage` states the difference explicitly so it can't.
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/coverage.d.ts

@@ -0,0 +1,68 @@
+import type { Result } from 'vpndetection';
+/**
+ * What a lookup result did and did not cover.
+ *
+ * The API's contract is that a missing member means "not in this plan", never
+ * "we checked and found nothing". A model reading a served body cannot tell the
+ * two apart and will report an absent `is_tor` as a negative finding, so every
+ * result carries this alongside it.
+ */
+export interface Coverage {
+    /** Members the API returned, so they were actually checked. */
+    included: string[];
+    /** Members this plan does not buy. Absent, not false. */
+    not_included: string[];
+    note: string;
+}
+/**
+ * The answer in the names the API publishes, which is what a model has read the
+ * docs in and what this server's `outputSchema` declares.
+ *
+ * A served answer already carries it as `raw`. A bogon does not: the SDK answers
+ * those locally onto its own camelCase members and leaves `raw` empty. Rebuilding
+ * it from the spec's own property types avoids a second copy of the wire names
+ * here, and lands on the documented bogon shape by construction - every flag
+ * present and false, every detail object present and empty.
+ */
+export declare function wireBody(result: Result): Record<string, unknown>;
+/**
+ * Derives coverage from the result body alone.
+ *
+ * Deliberately no tier table: the members are read from the pinned spec and the
+ * absent ones are whatever the API left out, so a dataset added to `ip_api`
+ * starts appearing here as soon as `scripts/download-spec.sh` is re-run. The
+ * caller's tier is never named, because the plan's identity is not the useful
+ * fact - what it failed to check is.
+ */
+export declare function coverageOf(body: Record<string, unknown>): Coverage;
+/**
+ * One coverage for a whole batch, taken from the first served answer.
+ *
+ * A bogon is synthesized locally in the full shape, so reading coverage off one
+ * would report every dataset as covered whatever the plan actually buys. Errors
+ * carry no shape at all. With neither available there is nothing honest to say,
+ * which is what `NOTE_UNKNOWN` says.
+ */
+export declare function batchCoverage(bodies: Record<string, unknown>[]): Coverage;
+export declare const COVERAGE_SCHEMA: {
+    readonly type: "object";
+    readonly description: "Which datasets this result covered. Read `note` before interpreting any absent field.";
+    readonly properties: {
+        readonly included: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly not_included: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly note: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["included", "not_included", "note"];
+};

package/dist/coverage.js

@@ -0,0 +1,85 @@
+import { LOOKUP_GATED_MEMBERS, LOOKUP_MEMBERS, LOOKUP_RESULT_SCHEMA } from './schema.gen.js';
+const NOTE_PARTIAL = 'The fields in not_included were not returned, because this API key\'s plan does '
+    + 'not include them. Their absence is not a negative result: the address was never checked '
+    + 'against those datasets. Do not state or imply that the address is not hosting, a relay, Tor, '
+    + 'a CDN or a proxy on the basis of a field missing from this result.';
+const NOTE_FULL = 'This plan covers every dataset the API serves, so every field was checked. A '
+    + 'false flag here is a real negative result.';
+const NOTE_BOGON = 'This is a private, reserved or otherwise non-routable address. It was answered '
+    + 'locally without calling the API, so every flag is false by definition rather than by lookup, '
+    + 'and it cost nothing against the key\'s allowance.';
+const NOTE_UNKNOWN = 'No served answer was available to derive coverage from, so this batch says '
+    + 'nothing about which datasets the plan covers.';
+/**
+ * The answer in the names the API publishes, which is what a model has read the
+ * docs in and what this server's `outputSchema` declares.
+ *
+ * A served answer already carries it as `raw`. A bogon does not: the SDK answers
+ * those locally onto its own camelCase members and leaves `raw` empty. Rebuilding
+ * it from the spec's own property types avoids a second copy of the wire names
+ * here, and lands on the documented bogon shape by construction - every flag
+ * present and false, every detail object present and empty.
+ */
+export function wireBody(result) {
+    if (!result.isBogon) {
+        return result.raw;
+    }
+    const out = { ip: result.ip, is_bogon: true };
+    for (const [name, schema] of Object.entries(LOOKUP_RESULT_SCHEMA.properties ?? {})) {
+        if (name === 'ip') {
+            continue;
+        }
+        const type = schema.type;
+        if (type === 'boolean') {
+            out[name] = false;
+        }
+        else if (type === 'object') {
+            out[name] = {};
+        }
+    }
+    return out;
+}
+/**
+ * Derives coverage from the result body alone.
+ *
+ * Deliberately no tier table: the members are read from the pinned spec and the
+ * absent ones are whatever the API left out, so a dataset added to `ip_api`
+ * starts appearing here as soon as `scripts/download-spec.sh` is re-run. The
+ * caller's tier is never named, because the plan's identity is not the useful
+ * fact - what it failed to check is.
+ */
+export function coverageOf(body) {
+    const included = LOOKUP_MEMBERS.filter((m) => m in body);
+    const notIncluded = LOOKUP_GATED_MEMBERS.filter((m) => !(m in body));
+    let note = notIncluded.length === 0 ? NOTE_FULL : NOTE_PARTIAL;
+    if (body['is_bogon'] === true) {
+        note = NOTE_BOGON;
+    }
+    return { included: included, not_included: notIncluded, note: note };
+}
+/**
+ * One coverage for a whole batch, taken from the first served answer.
+ *
+ * A bogon is synthesized locally in the full shape, so reading coverage off one
+ * would report every dataset as covered whatever the plan actually buys. Errors
+ * carry no shape at all. With neither available there is nothing honest to say,
+ * which is what `NOTE_UNKNOWN` says.
+ */
+export function batchCoverage(bodies) {
+    const served = bodies.find((b) => b['is_bogon'] !== true);
+    if (served === undefined) {
+        return { included: [], not_included: [], note: NOTE_UNKNOWN };
+    }
+    return coverageOf(served);
+}
+export const COVERAGE_SCHEMA = {
+    type: 'object',
+    description: 'Which datasets this result covered. Read `note` before interpreting any absent field.',
+    properties: {
+        included: { type: 'array', items: { type: 'string' } },
+        not_included: { type: 'array', items: { type: 'string' } },
+        note: { type: 'string' },
+    },
+    required: ['included', 'not_included', 'note'],
+};
+//# sourceMappingURL=coverage.js.map

package/dist/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createTools, registerTools, BATCH_LIMIT } from './tools.js';
+export type { ToolContext, ToolDef } from './tools.js';
+export { coverageOf, batchCoverage, COVERAGE_SCHEMA } from './coverage.js';
+export type { Coverage } from './coverage.js';
+export { LOOKUP_MEMBERS, LOOKUP_GATED_MEMBERS, SPEC_VERSION } from './schema.gen.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createTools, registerTools, BATCH_LIMIT } from './tools.js';
+export { coverageOf, batchCoverage, COVERAGE_SCHEMA } from './coverage.js';
+export { LOOKUP_MEMBERS, LOOKUP_GATED_MEMBERS, SPEC_VERSION } from './schema.gen.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAErE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3E,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/schema.gen.d.ts

@@ -0,0 +1,12 @@
+export declare const LOOKUP_MEMBERS: readonly string[];
+export declare const LOOKUP_GATED_MEMBERS: readonly string[];
+export declare const SPEC_VERSION = "2026.09.10";
+export interface ObjectSchema {
+    type: 'object';
+    properties?: Record<string, object>;
+    required?: string[];
+    [k: string]: unknown;
+}
+export declare const LOOKUP_RESULT_SCHEMA: ObjectSchema;
+export declare const LICENSED_DATASET_SCHEMA: ObjectSchema;
+export declare const DATASET_METADATA_SCHEMA: ObjectSchema;

package/dist/schema.gen.js

@@ -0,0 +1,492 @@
+// Code generated by scripts/gen-schema.mjs from spec/openapi.json. DO NOT EDIT.
+export const LOOKUP_MEMBERS = [
+    'ip',
+    'is_vpn',
+    'is_hosting',
+    'is_relay',
+    'is_tor',
+    'is_cdn',
+    'is_resproxy',
+    'is_dcproxy',
+    'is_mobproxy',
+    'vpn',
+    'hosting',
+    'relay',
+    'tor',
+    'cdn',
+    'resproxy',
+    'dcproxy',
+    'mobproxy',
+];
+export const LOOKUP_GATED_MEMBERS = [
+    'is_hosting',
+    'is_relay',
+    'is_tor',
+    'is_cdn',
+    'is_resproxy',
+    'is_dcproxy',
+    'is_mobproxy',
+    'vpn',
+    'hosting',
+    'relay',
+    'tor',
+    'cdn',
+    'resproxy',
+    'dcproxy',
+    'mobproxy',
+];
+export const SPEC_VERSION = '2026.09.10';
+export const LOOKUP_RESULT_SCHEMA = {
+    "type": "object",
+    "description": "The union of every plan's answer. Only `ip` and `is_vpn` are guaranteed;\neach remaining field is present when your plan includes it, and absent\notherwise. A client that must work across plans should treat an absent\nflag as unknown rather than as `false`.\n",
+    "required": [
+        "ip",
+        "is_vpn"
+    ],
+    "properties": {
+        "ip": {
+            "type": "string",
+            "description": "The address that was looked up, normalized."
+        },
+        "is_vpn": {
+            "type": "boolean",
+            "description": "Whether the address is VPN infrastructure. Keys off presence in the\nVPN dataset, so an unattributed range with no provider is still\n`true`.\n"
+        },
+        "is_hosting": {
+            "type": "boolean",
+            "description": "Whether the address belongs to a hosting or cloud provider. Starter and above."
+        },
+        "is_relay": {
+            "type": "boolean",
+            "description": "Whether the address is a privacy relay egress. Starter and above."
+        },
+        "is_tor": {
+            "type": "boolean",
+            "description": "Whether the address is a Tor node. Starter and above."
+        },
+        "is_cdn": {
+            "type": "boolean",
+            "description": "Whether the address belongs to a CDN. Starter and above."
+        },
+        "is_resproxy": {
+            "type": "boolean",
+            "description": "Whether the address was seen in a residential proxy pool. Scale and above."
+        },
+        "is_dcproxy": {
+            "type": "boolean",
+            "description": "Whether the address was seen in a datacenter proxy pool. Scale and above."
+        },
+        "is_mobproxy": {
+            "type": "boolean",
+            "description": "Whether the address was seen in a mobile proxy pool. Scale and above."
+        },
+        "vpn": {
+            "type": "object",
+            "description": "Detail for `is_vpn`. Empty when `is_vpn` is false. Starter and above.\n",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The VPN provider, or an empty string for an unattributed range."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date this address was observed as VPN infrastructure."
+                },
+                "confidence": {
+                    "type": "string",
+                    "description": "How strongly the attribution is supported. Max only."
+                },
+                "method": {
+                    "type": "string",
+                    "description": "The class of evidence the attribution rests on, one of four values.\nMax only.\n\n`scan` - we spoke the VPN protocol to the address ourselves and got a\nvalid server response. `scrape` - the operator published the address\nthrough its own API, client or configuration. `registry` - public\nregistration or naming records attribute it to the operator.\n`infer` - the address was extrapolated from confirmed neighbours in\nthe same block.\n"
+                }
+            }
+        },
+        "hosting": {
+            "type": "object",
+            "description": "Detail for `is_hosting`. Empty when false. Scale and above.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The provider, or an empty string where the dataset has none."
+                },
+                "confidence": {
+                    "type": "string",
+                    "description": "How strongly the classification is supported."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date this address was observed in this dataset."
+                }
+            }
+        },
+        "relay": {
+            "type": "object",
+            "description": "Detail for `is_relay`. Empty when false. Scale and above.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The provider, or an empty string where the dataset has none."
+                },
+                "confidence": {
+                    "type": "string",
+                    "description": "How strongly the classification is supported."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date this address was observed in this dataset."
+                }
+            }
+        },
+        "tor": {
+            "type": "object",
+            "description": "Detail for `is_tor`. Empty when false. Scale and above. The tor\ndataset carries no provider, so `provider` is always an empty string.\n",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The provider, or an empty string where the dataset has none."
+                },
+                "confidence": {
+                    "type": "string",
+                    "description": "How strongly the classification is supported."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date this address was observed in this dataset."
+                }
+            }
+        },
+        "cdn": {
+            "type": "object",
+            "description": "Detail for `is_cdn`. Empty when false. Scale and above.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The provider, or an empty string where the dataset has none."
+                },
+                "confidence": {
+                    "type": "string",
+                    "description": "How strongly the classification is supported."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date this address was observed in this dataset."
+                }
+            }
+        },
+        "resproxy": {
+            "type": "object",
+            "description": "Detail for `is_resproxy`. Empty when false. Max only.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The proxy network, or an empty string where unattributed."
+                },
+                "first_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The earliest date within the window this address was seen in the pool."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date within the window this address was seen in the pool."
+                },
+                "hits": {
+                    "type": "integer",
+                    "description": "How many times the address was observed in the pool during the window."
+                },
+                "hits_days_pct": {
+                    "type": "integer",
+                    "description": "The share of days in the window on which the address was seen, as a\npercentage. A high value means a stable pool member rather than a\none-off sighting.\n"
+                },
+                "providers_num": {
+                    "type": "integer",
+                    "description": "How many distinct proxy networks this address was seen in."
+                }
+            }
+        },
+        "dcproxy": {
+            "type": "object",
+            "description": "Detail for `is_dcproxy`. Empty when false. Max only.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The proxy network, or an empty string where unattributed."
+                },
+                "first_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The earliest date within the window this address was seen in the pool."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date within the window this address was seen in the pool."
+                },
+                "hits": {
+                    "type": "integer",
+                    "description": "How many times the address was observed in the pool during the window."
+                },
+                "hits_days_pct": {
+                    "type": "integer",
+                    "description": "The share of days in the window on which the address was seen, as a\npercentage. A high value means a stable pool member rather than a\none-off sighting.\n"
+                },
+                "providers_num": {
+                    "type": "integer",
+                    "description": "How many distinct proxy networks this address was seen in."
+                }
+            }
+        },
+        "mobproxy": {
+            "type": "object",
+            "description": "Detail for `is_mobproxy`. Empty when false. Max only.",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "description": "The proxy network, or an empty string where unattributed."
+                },
+                "first_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The earliest date within the window this address was seen in the pool."
+                },
+                "last_seen": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "The most recent date within the window this address was seen in the pool."
+                },
+                "hits": {
+                    "type": "integer",
+                    "description": "How many times the address was observed in the pool during the window."
+                },
+                "hits_days_pct": {
+                    "type": "integer",
+                    "description": "The share of days in the window on which the address was seen, as a\npercentage. A high value means a stable pool member rather than a\none-off sighting.\n"
+                },
+                "providers_num": {
+                    "type": "integer",
+                    "description": "How many distinct proxy networks this address was seen in."
+                }
+            }
+        }
+    }
+};
+export const LICENSED_DATASET_SCHEMA = {
+    "type": "object",
+    "description": "One dataset FAMILY your organization is licensed for. A license covers\nthe family, while a download names a specific version, so the ids you\npass to the download and checksum endpoints come from `versions`.\n",
+    "properties": {
+        "base": {
+            "type": "string",
+            "description": "The dataset family, e.g. `vpn_ip`. What the license is held against."
+        },
+        "name": {
+            "type": "string"
+        },
+        "summary": {
+            "type": "string"
+        },
+        "license_type": {
+            "type": "string",
+            "enum": [
+                "evaluation",
+                "standard",
+                "redistribute"
+            ],
+            "description": "What your license permits you to do with the data."
+        },
+        "starts": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+        },
+        "expires": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "A hard stop. Null when the license has no end date, which is the normal case for a rolling agreement, and when there is no license. A rolling license reports its turnover date in renews_at instead."
+        },
+        "renews_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "When a rolling license next renews. Null when the license has no defined term, when expires sets a hard stop instead, and when there is no license."
+        },
+        "notice_due_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "The last day notice of non-renewal can be given for the term ending at renews_at. Null whenever renews_at is, and when the agreement records no notice period."
+        },
+        "in_term": {
+            "type": "boolean",
+            "description": "False when the license has lapsed; downloads are refused."
+        },
+        "standing": {
+            "type": "string",
+            "enum": [
+                "expired",
+                "licensed",
+                "unlicensed"
+            ],
+            "description": "`licensed` is a live grant, `expired` one whose term has ended, and\n`unlicensed` a dataset published but never bought.\n"
+        },
+        "versions": {
+            "type": "array",
+            "description": "Every published version of this family. The `id` here is what the\ndownload and checksum endpoints take.\n",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "The versioned dataset id, e.g. `vpn_ip_v1`. Pass this to download."
+                    },
+                    "version": {
+                        "type": "integer"
+                    },
+                    "summary": {
+                        "type": "string"
+                    },
+                    "formats": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "format": {
+                                    "type": "string",
+                                    "enum": [
+                                        "csvgz",
+                                        "mmdb"
+                                    ]
+                                },
+                                "bytes": {
+                                    "type": "integer",
+                                    "nullable": true,
+                                    "description": "Size of the published file, or null when it has not been published yet"
+                                }
+                            },
+                            "required": [
+                                "format",
+                                "bytes"
+                            ]
+                        }
+                    },
+                    "sampleFormats": {
+                        "type": "array",
+                        "description": "The formats an evaluation sample is published in, if any.",
+                        "items": {
+                            "type": "string",
+                            "enum": [
+                                "csvgz",
+                                "mmdb"
+                            ]
+                        }
+                    }
+                },
+                "required": [
+                    "id",
+                    "version",
+                    "formats"
+                ]
+            }
+        }
+    },
+    "required": [
+        "base",
+        "name",
+        "summary",
+        "license_type",
+        "starts",
+        "expires",
+        "renews_at",
+        "notice_due_at",
+        "in_term",
+        "standing",
+        "versions"
+    ]
+};
+export const DATASET_METADATA_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "id": {
+            "type": "string"
+        },
+        "update_freq": {
+            "type": "string",
+            "description": "How often a new build is published"
+        },
+        "updated": {
+            "type": "string",
+            "format": "date"
+        },
+        "entries": {
+            "type": "integer",
+            "description": "Row count in the current build"
+        },
+        "schema": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string"
+                        },
+                        "type": {
+                            "type": "string"
+                        },
+                        "description": {
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "type"
+                    ]
+                }
+            },
+            "description": "Columns, keyed by format"
+        },
+        "sample": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "array",
+                "items": {
+                    "type": "object"
+                }
+            },
+            "description": "A few real rows, keyed by format"
+        },
+        "size": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "integer"
+            },
+            "description": "Bytes per format"
+        },
+        "sample_size": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "integer"
+            },
+            "description": "Bytes per format of the evaluation sample, where one is published"
+        },
+        "sample_entries": {
+            "type": "integer",
+            "description": "Row count in the evaluation sample"
+        }
+    },
+    "required": [
+        "id",
+        "updated",
+        "entries",
+        "schema"
+    ]
+};
+//# sourceMappingURL=schema.gen.js.map

package/dist/schema.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.gen.js","sourceRoot":"","sources":["../src/schema.gen.ts"],"names":[],"mappings":"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"}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// The stdio entry point: the process an MCP client spawns.
+//
+// This is the one file that reads the environment. The MCP specification tells
+// stdio servers to take credentials that way rather than through the protocol's
+// OAuth profile, and everything below it takes its configuration as arguments.
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { VPNDetection } from 'vpndetection';
+import { createTools, registerTools } from './tools.js';
+const version = createRequire(import.meta.url)('../package.json').version;
+async function main() {
+    const apiKey = process.env['VPNDETECTION_API_KEY'];
+    const client = new VPNDetection({
+        ...(apiKey === undefined || apiKey === '' ? {} : { apiKey: apiKey }),
+        ...(process.env['VPNDETECTION_BASE_URL'] === undefined
+            ? {} : { baseUrl: process.env['VPNDETECTION_BASE_URL'] }),
+    });
+    const server = new Server({ name: 'vpndetection', version: version }, { capabilities: { tools: {} } });
+    registerTools(server, createTools({ client: client }));
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    // stdout carries the protocol, so a diagnostic can only go to stderr.
+    console.error(err);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":";AAEA,2DAA2D;AAC3D,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,OAAiB,CAAC;AAEpF,KAAK,UAAU,IAAI;IACf,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;QAC5B,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QACpE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,SAAS;YAClD,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,EAAE,CAAC;KAChE,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,MAAM,CACrB,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,EAC1C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAClC,CAAC;IACF,aAAa,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAEvD,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC1B,sEAAsE;IACtE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { VPNDetection } from 'vpndetection';
+/** The most addresses one `lookup_ips` call may carry. */
+export declare const BATCH_LIMIT = 100;
+export interface ToolContext {
+    client: VPNDetection;
+    /**
+     * Whether to offer the dataset tools. On by default: a key without the
+     * `db.download` scope gets a plain refusal from the API, which reads better
+     * than a tool that silently does not exist, and deciding otherwise would
+     * mean re-validating the key here against a policy `db_dl_api` owns.
+     */
+    database?: boolean;
+}
+export interface ToolDef {
+    tool: Tool;
+    handler: (args: Record<string, unknown>) => Promise<CallToolResult>;
+}
+/**
+ * The tool manifest, and the single place either transport gets it from.
+ *
+ * Descriptions are read by a model rather than a developer, so they say what
+ * the tool answers and what it costs, not how it is implemented.
+ */
+export declare function createTools(ctx: ToolContext): ToolDef[];
+/** Mounts a manifest on a server. Both transports use this and nothing else. */
+export declare function registerTools(server: Server, defs: ToolDef[]): void;

package/dist/tools.js

@@ -0,0 +1,258 @@
+import { z } from 'zod';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { batchCoverage, COVERAGE_SCHEMA, coverageOf, wireBody } from './coverage.js';
+import { DATASET_METADATA_SCHEMA, LICENSED_DATASET_SCHEMA, LOOKUP_RESULT_SCHEMA, } from './schema.gen.js';
+/** The most addresses one `lookup_ips` call may carry. */
+export const BATCH_LIMIT = 100;
+/**
+ * The tool manifest, and the single place either transport gets it from.
+ *
+ * Descriptions are read by a model rather than a developer, so they say what
+ * the tool answers and what it costs, not how it is implemented.
+ */
+export function createTools(ctx) {
+    const defs = [
+        {
+            tool: {
+                name: 'lookup_ip',
+                title: 'Look up an IP address',
+                description: 'Classify a single IPv4 or IPv6 address: whether it belongs to a VPN, '
+                    + 'a residential, datacenter or mobile proxy, a Tor node, a public relay, a '
+                    + 'hosting provider or a CDN, with the provider name where we have one. '
+                    + 'Private and reserved addresses are answered locally and cost nothing. '
+                    + 'Always read `coverage.note` before concluding anything from a field that is '
+                    + 'not in the result.',
+                inputSchema: jsonSchema(z.object({
+                    ip: z.string().describe('The IPv4 or IPv6 address to classify.'),
+                })),
+                outputSchema: objectSchema({
+                    result: LOOKUP_RESULT_SCHEMA,
+                    coverage: COVERAGE_SCHEMA,
+                }, ['result', 'coverage']),
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+            },
+            handler: (args) => lookupIp(ctx, args),
+        },
+        {
+            tool: {
+                name: 'lookup_ips',
+                title: 'Look up several IP addresses',
+                description: `Classify up to ${BATCH_LIMIT} addresses in one call, returning a map `
+                    + 'keyed by address so duplicates collapse and the order you passed them stops '
+                    + 'mattering. Prefer this over repeated `lookup_ip` calls when you already have '
+                    + 'the list, for example when triaging a log file. An address that fails '
+                    + 'carries its error in place of a result rather than failing the batch.',
+                inputSchema: jsonSchema(z.object({
+                    ips: z.array(z.string()).min(1).max(BATCH_LIMIT)
+                        .describe(`The addresses to classify, at most ${BATCH_LIMIT}.`),
+                })),
+                outputSchema: objectSchema({
+                    results: {
+                        type: 'object',
+                        description: 'Keyed by address. A value is either a result or an error.',
+                        additionalProperties: true,
+                    },
+                    coverage: COVERAGE_SCHEMA,
+                }, ['results', 'coverage']),
+                annotations: {
+                    readOnlyHint: true,
+                    idempotentHint: true,
+                    openWorldHint: true,
+                },
+            },
+            handler: (args) => lookupIps(ctx, args),
+        },
+    ];
+    if (ctx.database !== false) {
+        defs.push(...databaseTools(ctx));
+    }
+    // A handler NEVER throws: an upstream 404 or a rejected argument is a result
+    // the model can read and correct itself from, while a JSON-RPC protocol error
+    // is not. Wrapping here rather than in `registerTools` keeps that true for
+    // any consumer of a ToolDef, including a transport that mounts its own.
+    return defs.map((d) => ({ tool: d.tool, handler: guard(d.handler) }));
+}
+/** Mounts a manifest on a server. Both transports use this and nothing else. */
+export function registerTools(server, defs) {
+    const byName = new Map(defs.map((d) => [d.tool.name, d]));
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: defs.map((d) => d.tool) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const def = byName.get(req.params.name);
+        if (def === undefined) {
+            throw new Error(`Unknown tool: ${req.params.name}`);
+        }
+        return await def.handler(req.params.arguments ?? {});
+    });
+}
+function guard(handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (err) {
+            return toolError(err);
+        }
+    };
+}
+async function lookupIp(ctx, args) {
+    const { ip } = z.object({ ip: z.string() }).parse(args);
+    const body = wireBody(await ctx.client.lookup(ip));
+    return ok({ result: body, coverage: coverageOf(body) });
+}
+async function lookupIps(ctx, args) {
+    const { ips } = z.object({
+        ips: z.array(z.string()).min(1).max(BATCH_LIMIT),
+    }).parse(args);
+    const answers = await ctx.client.lookupBatch(ips);
+    const results = {};
+    const served = [];
+    for (const [addr, answer] of answers) {
+        const failed = asClientError(answer);
+        if (failed !== undefined) {
+            results[addr] = { error: { kind: failed.kind, message: failed.message } };
+            continue;
+        }
+        const body = wireBody(answer);
+        results[addr] = body;
+        served.push(body);
+    }
+    return ok({ results: results, coverage: batchCoverage(served) });
+}
+function databaseTools(ctx) {
+    const formats = z.enum(['csvgz', 'mmdb']);
+    return [
+        {
+            tool: {
+                name: 'list_databases',
+                title: 'List licensed datasets',
+                description: 'The datasets this API key\'s organisation is licensed to download, '
+                    + 'with the licence type and term. A dataset absent from this list is one the '
+                    + 'organisation does not hold.',
+                inputSchema: { type: 'object', additionalProperties: false },
+                outputSchema: objectSchema({
+                    datasets: { type: 'array', items: LICENSED_DATASET_SCHEMA },
+                }, ['datasets']),
+                annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            },
+            handler: async () => {
+                return ok({ datasets: await ctx.client.database.list() });
+            },
+        },
+        {
+            tool: {
+                name: 'database_metadata',
+                title: 'Describe a dataset',
+                description: 'The shape of a dataset before you fetch it: the columns in each '
+                    + 'published format with their types, a few sample rows, the row count, the '
+                    + 'build date and the file sizes. Use this to answer questions about what a '
+                    + 'dataset contains without downloading it - the files reach several GB.',
+                inputSchema: jsonSchema(z.object({
+                    dataset_id: z.string().describe('The dataset id, as returned by `list_databases`.'),
+                })),
+                outputSchema: DATASET_METADATA_SCHEMA,
+                annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            },
+            handler: async (args) => {
+                const { dataset_id } = z.object({ dataset_id: z.string() }).parse(args);
+                return ok(await ctx.client.database.metadata(dataset_id));
+            },
+        },
+        {
+            tool: {
+                name: 'database_checksum',
+                title: 'Get a dataset\'s checksums',
+                description: 'The published digests for one dataset file, for verifying a copy you '
+                    + 'already hold or deciding whether a build has changed since you last fetched it.',
+                inputSchema: jsonSchema(z.object({
+                    dataset_id: z.string().describe('The dataset id, as returned by `list_databases`.'),
+                    format: formats.describe('Which published file to digest.'),
+                })),
+                outputSchema: {
+                    type: 'object',
+                    properties: { checksums: { type: 'object', additionalProperties: true } },
+                    required: ['checksums'],
+                },
+                annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            },
+            handler: async (args) => {
+                const parsed = z.object({
+                    dataset_id: z.string(),
+                    format: formats,
+                }).parse(args);
+                const checksums = await ctx.client.database.checksums(parsed.dataset_id, parsed.format);
+                return ok({ checksums: checksums });
+            },
+        },
+    ];
+}
+/**
+ * The serialized structured content IS the text block, rather than a prose
+ * summary beside it. The coverage note lives inside the structure, so writing
+ * it once puts it in front of both a client that reads `structuredContent` and
+ * one that only renders `content`.
+ */
+function ok(structured) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+        structuredContent: structured,
+    };
+}
+/**
+ * An error carries no `structuredContent`, deliberately.
+ *
+ * A tool that declares an `outputSchema` has every structured result validated
+ * against it by the client, and an error is not shaped like a success - so
+ * attaching one turns a readable failure into a protocol error the model cannot
+ * act on. The text block is what it reads instead.
+ */
+function toolError(err) {
+    const known = asClientError(err);
+    const detail = known !== undefined
+        ? { kind: known.kind, message: known.message, retryable: known.retryable === true }
+        : { kind: 'internal', message: err instanceof Error ? err.message : String(err) };
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: detail }, null, 2) }],
+        isError: true,
+    };
+}
+/**
+ * Recognises a `VPNDetectionError` by SHAPE, not by `instanceof`.
+ *
+ * This package and whatever mounts it can each end up with their own copy of the
+ * `vpndetection` module - the hosted service depends on both - and two copies of
+ * one class are two identities, so `instanceof` silently returns false and every
+ * upstream failure degrades to a generic `internal`. A caller then sees "internal"
+ * for what was really `unauthorized`, and loses the `retryable` flag that decides
+ * whether trying again is worth anything.
+ */
+function asClientError(err) {
+    if (err === null || typeof err !== 'object') {
+        return undefined;
+    }
+    const e = err;
+    if (e.name !== 'VPNDetectionError' || typeof e.kind !== 'string') {
+        return undefined;
+    }
+    return e;
+}
+// One zod declaration yields both the published schema and the runtime parse, so
+// a cap advertised to a client is the same cap the handler enforces.
+function jsonSchema(schema) {
+    const out = z.toJSONSchema(schema, { io: 'input' });
+    delete out['$schema'];
+    return { ...out, type: 'object' };
+}
+function objectSchema(properties, required) {
+    return {
+        type: 'object',
+        properties: properties,
+        required: required,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "vpndetection-mcp",
+  "version": "1.0.0",
+  "description": "Official MCP server for the VPNDetection API. Gives an LLM agent VPN, proxy, Tor, hosting and CDN detection for any IP address.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://vpndetection.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vpndetection-io/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vpndetection-io/mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vpn",
+    "vpn-detection",
+    "proxy-detection",
+    "tor",
+    "ip-intelligence",
+    "fraud-prevention",
+    "llm",
+    "agent"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "vpndetection-mcp": "./dist/stdio.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "vpndetection": "^1.7.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "generate": "node scripts/gen-schema.mjs",
+    "build": "rm -rf dist && pnpm run generate && tsc",
+    "test": "pnpm run build && node --test test/*.test.mjs"
+  }
+}