@prooftell/mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProofTell
+
+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

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @prooftell/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[ProofTell](https://prooftell.com/integrations?utm_source=mcp&utm_medium=integration)'s MCP server: the checks of
+ProofTell's public API (https://prooftell.com/docs) as tools for Claude, Cursor, VS Code and any client of the
+Model Context Protocol. Ask the assistant to check a phone number, an email address or an IP address, or to assess
+the risk of a sign-up; it calls ProofTell with your key and reads the answer. The server runs on your machine
+(stdio) and stores nothing.
+
+## The key
+
+Create a key in the ProofTell dashboard (Developers → Integrations), named after this platform. A `pt_test_` key is
+the free sandbox: simulated, deterministic answers. A `pt_live_` key spends the account's balance. The server reads
+it from the environment variable `PROOFTELL_API_KEY`, set in the client's configuration below.
+
+## Adding it to a client
+
+It needs Node.js 18 or later; `npx` fetches the server on first use.
+
+**Claude Code:**
+
+```sh
+claude mcp add prooftell --env PROOFTELL_API_KEY=pt_test_… -- npx -y @prooftell/mcp
+```
+
+**Claude Desktop:** Settings → Developer → Edit config, then in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "prooftell": {
+      "command": "npx",
+      "args": ["-y", "@prooftell/mcp"],
+      "env": { "PROOFTELL_API_KEY": "pt_test_…" }
+    }
+  }
+}
+```
+
+**Cursor:** the same block in `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project).
+
+**VS Code** (agent mode): in `.vscode/mcp.json`; VS Code asks for the key once and keeps it out of the file.
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "prooftell-key", "description": "ProofTell API key", "password": true }
+  ],
+  "servers": {
+    "prooftell": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@prooftell/mcp"],
+      "env": { "PROOFTELL_API_KEY": "${input:prooftell-key}" }
+    }
+  }
+}
+```
+
+## The tools
+
+Each check is charged per check from your balance; the sandbox is free. The answer is the API's JSON, unchanged.
+
+| Tool | Title | Call | Arguments |
+|---|---|---|---|
+| `look_up_phone_number` | Look up a phone number | `POST /v1/phone` | `phone` (required); `country`, for a number in national format; `level`: `basic`, `line_type` (the default), `current_carrier`, `line_status`, `fraud_score`, each including the ones before it |
+| `verify_email_address` | Verify an email address | `POST /v1/email` | `email` (required); `timeout`, 1000 to 45000 ms |
+| `look_up_ip_address` | Look up an IP address | `POST /v1/ip` | `ip` (required) |
+| `assess_identity_risk` | Assess the risk of an identity | `POST /v1/assess` | any of `phone`, `email`, `ip` (one at least); `country`; `reference` |
+| `get_balance` | Get the account's balance | `GET /v1/balance` | — (free) |
+
+An assessment answers a `score` from 0 to 100, a `verdict` (allow, review, deny) and the `reasons` that added to the
+score; each signal's own result is under `signals`. A failed call comes back as a tool error with the API's message
+and code — `insufficient_balance` names what the check needs and what to top up, `rate_limited` is a burst above the
+key's rate, `invalid_api_key` a wrong or revoked key — so the assistant can say what to do.
+
+## The sandbox
+
+With a `pt_test_` key every call is simulated, deterministic and free: `+447700900123` is a GB mobile,
+`+15005550003` is not valid; `jane@example.com` is deliverable, `disposable@sandbox.prooftell.com` disposable;
+`203.0.113.1` is a clean US address, `203.0.113.66` Tor; an assessment of `+447700900123` with `203.0.113.1` is a
+`geo_mismatch`, allowed with a score of 15. The full list is in the API reference: https://prooftell.com/docs.
+
+## Development
+
+Plain JavaScript (ES modules), no build step: `src/index.js` (the server), `src/tools.js` (the tools and their
+schemas), `src/api.js` (the requests).
+
+```sh
+npm install
+npm test     # the SDK's client spawns the server: the tools' list, the requests against a local stand-in for the
+             # API, the errors; with PROOFTELL_TEST_KEY set to a sandbox key (read into the command, never written
+             # down), every tool against staging as well
+```
+
+`PROOFTELL_BASE_URL` points the server at another API (`https://api.prooftell.dev`, staging); it is read from the
+environment only.
+
+## Releasing
+
+1. npm, by GitHub Actions with provenance (`.github/workflows/release-mcp.yml` at the root of
+   [prooftell/integrations](https://github.com/prooftell/integrations)): bump `version` in `package.json` and in
+   `server.json` (both places), commit, tag `mcp-v<version>` and push the tag. The first release publishes with the
+   repository secret `NPM_TOKEN` (a granular token with Read and write on all packages and Bypass two-factor
+   authentication); after it, npm's trusted publishing (the package's settings, Publish access → Trusted Publishers
+   → GitHub Actions, owner `prooftell`, repository `integrations`, workflow `release-mcp.yml`, "Allow npm publish"
+   ticked), the secret and the token deleted. npm expires a new trusted publisher that no successful publish has used within 2 days (then: delete it,
+   create it again and release within 2 days); the token-free path was first proven with 1.0.1.
+2. The official MCP Registry, once the version is on npm, from this folder with
+   [mcp-publisher](https://github.com/modelcontextprotocol/registry/releases): `mcp-publisher login dns --domain
+   prooftell.com --private-key <the key's hex>`, then `mcp-publisher publish`. The name `com.prooftell/mcp` is proven
+   by the TXT record `v=MCPv1; k=ed25519; p=…` at prooftell.com's apex; `package.json`'s `mcpName` ties the npm
+   package to it. A version published there cannot be changed or removed: a fix is a new version.
+
+## Resources
+
+- ProofTell: https://prooftell.com/integrations?utm_source=mcp&utm_medium=integration
+- The API reference: https://prooftell.com/docs
+- Support: support@prooftell.com
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@prooftell/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "ProofTell's MCP server: phone, email and IP checks and an identity's risk score as tools for Claude, Cursor, VS Code and any MCP client, with one API key.",
+  "license": "MIT",
+  "mcpName": "com.prooftell/mcp",
+  "homepage": "https://prooftell.com/integrations?utm_source=mcp&utm_medium=integration",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "prooftell",
+    "phone-validation",
+    "email-verification",
+    "ip-intelligence",
+    "fraud"
+  ],
+  "author": {
+    "name": "ProofTell",
+    "email": "support@prooftell.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prooftell/integrations.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/prooftell/integrations/issues",
+    "email": "support@prooftell.com"
+  },
+  "type": "module",
+  "bin": {
+    "prooftell-mcp": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.0.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,67 @@
+// ProofTell's public API, as the MCP server calls it: one request per tool, the answer back unchanged, or an
+// `ApiError` carrying the api's own message, code and status. The key comes from the server's environment
+// (`PROOFTELL_API_KEY`); `PROOFTELL_BASE_URL` points it elsewhere for tests only. Nothing here logs an input or the key.
+import { readFileSync } from 'node:fs'
+
+export const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+/** The shipped address. */
+export const BASE_URL = 'https://api.prooftell.com'
+
+/** Milliseconds a request may take: an email check may take 45 s at the mail server, plus the way there and back. */
+const REQUEST_TIMEOUT = 60000
+
+export class ApiError extends Error {
+  constructor (message, { code, status } = {}) {
+    super(message)
+    this.name = 'ApiError'
+    this.code = code
+    this.status = status
+  }
+}
+
+/** Sends one request and resolves with the api's JSON answer. `body` undefined makes it a GET. */
+export async function request (path, body, { env = process.env, fetchImpl = fetch } = {}) {
+  const key = (env.PROOFTELL_API_KEY || '').trim()
+  if (!key) {
+    throw new ApiError(
+      'No API key: set PROOFTELL_API_KEY in this MCP server\'s configuration to a key from the ProofTell dashboard ' +
+        '(Developers → Integrations). A pt_test_ key is the free sandbox.',
+      { code: 'no_key' },
+    )
+  }
+  const baseUrl = (env.PROOFTELL_BASE_URL || BASE_URL).replace(/\/+$/, '')
+  let response
+  try {
+    response = await fetchImpl(baseUrl + path, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: {
+        Authorization: `Bearer ${key}`,
+        Accept: 'application/json',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        'User-Agent': `prooftell-mcp/${version}`,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT),
+    })
+  } catch (err) {
+    const reason = err && err.name === 'TimeoutError' ? 'it did not answer within 60 seconds' : 'it could not be reached'
+    throw new ApiError(`The ProofTell API did not answer: ${reason}.`, { code: 'network' })
+  }
+  const text = await response.text()
+  let answer
+  try {
+    answer = text ? JSON.parse(text) : {}
+  } catch {
+    answer = undefined
+  }
+  if (!response.ok) {
+    const error = answer && answer.error
+    const message = error && error.message ? error.message : `The ProofTell API answered ${response.status}.`
+    throw new ApiError(message, { code: error && error.code, status: response.status })
+  }
+  if (answer === undefined) {
+    throw new ApiError('The ProofTell API answered something other than JSON.', { status: response.status })
+  }
+  return answer
+}

package/src/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// The ProofTell MCP server: the four checks and the balance as tools, over stdio, for an assistant that runs it
+// locally (Claude, Cursor, VS Code…). Configured by its environment: PROOFTELL_API_KEY, a key from the ProofTell
+// dashboard (Developers → Integrations). Nothing is written to stdout but the protocol; nothing is logged.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { version } from './api.js'
+import { TOOLS, run } from './tools.js'
+
+const INSTRUCTIONS = `ProofTell checks phone numbers, email addresses and IP addresses, and scores the risk of an identity from any
+mix of the three (0–100, with a verdict: allow, review or deny, and its reasons). Each check is charged per check from
+the account's balance; a pt_test_ key is the free sandbox, whose answers are simulated and deterministic:
++447700900123 is a GB mobile, jane@example.com is deliverable, 203.0.113.1 is a clean US address, 203.0.113.66 is Tor.
+Use assess_identity_risk to decide on a sign-up or an order; the single checks to clean or enrich one value. The API
+reference: https://prooftell.com/docs.`
+
+const server = new McpServer({ name: 'prooftell', title: 'ProofTell', version }, { instructions: INSTRUCTIONS })
+
+for (const tool of TOOLS) {
+  server.registerTool(
+    tool.name,
+    { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: tool.annotations },
+    (args) => run(tool, args),
+  )
+}
+
+await server.connect(new StdioServerTransport())

package/src/tools.js

@@ -0,0 +1,132 @@
+// The tools an assistant sees: the four checks, named as on every ProofTell connector (their titles; the names are
+// the same in snake_case, as MCP clients expect), and the account's balance. Each check is one request, charged per
+// check from the balance (the sandbox is free); the answer is the api's JSON, unchanged, as text and as structured
+// content. A failed call is a tool error carrying the api's message and code, so the assistant can say what to do.
+import { z } from 'zod'
+import { ApiError, request } from './api.js'
+
+const LEVELS = ['basic', 'line_type', 'current_carrier', 'line_status', 'fraud_score']
+
+/** A text argument: a required one must not be empty; an optional one may be, and is then not sent. */
+function text (max, description, required) {
+  return required ? z.string().min(1).max(max).describe(description) : z.string().max(max).describe(description).optional()
+}
+
+const PHONE = 'The phone number, in international format (E.164, e.g. +447700900123), or in national format with the country.'
+const EMAIL = 'The email address, e.g. jane@example.com.'
+const IP = 'The IPv4 or IPv6 address of the end user, e.g. 203.0.113.1.'
+const country = z
+  .string()
+  .regex(/^([A-Za-z]{2})?$/, 'a two-letter country code')
+  .describe('The two-letter country code (ISO 3166-1 alpha-2, e.g. GB) of a number given in national format.')
+  .optional()
+
+/** The answer of a call that cost something: neither read-only nor idempotent, since each call is charged. */
+const CHECK = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+
+export const TOOLS = [
+  {
+    name: 'look_up_phone_number',
+    title: 'Look up a phone number',
+    description:
+      'Checks a phone number: valid or not, its formats and country, then by level its line type, the carrier it is ' +
+      'on today, whether it is live on the network, or a fraud score. The levels are a ladder, each including the ' +
+      'ones before it and priced on its own: basic, line_type (the default), current_carrier, line_status, ' +
+      'fraud_score; what is not offered for the number comes back as unavailable, at no cost. Charged per check from ' +
+      'your balance; the sandbox (a pt_test_ key) is free.',
+    inputSchema: {
+      phone: text(32, PHONE, true),
+      country,
+      level: z.enum(LEVELS).optional().describe('How far to look; line_type when omitted.'),
+    },
+    annotations: { title: 'Look up a phone number', ...CHECK },
+    call: (args) => request('/v1/phone', args),
+  },
+  {
+    name: 'verify_email_address',
+    title: 'Verify an email address',
+    description:
+      'Checks whether an email address accepts mail: a verdict (deliverable, undeliverable, risky, unknown) with its ' +
+      'reason, the flags (disposable, role address, catch-all…), the safe action for a sign-up form, and a likely ' +
+      'correction of a misspelt domain. Charged per check from your balance; the sandbox (a pt_test_ key) is free.',
+    inputSchema: {
+      email: text(254, EMAIL, true),
+      timeout: z
+        .number()
+        .int()
+        .min(1000)
+        .max(45000)
+        .optional()
+        .describe('Milliseconds allowed for the mail server, 1000 to 45000 (the default); past it the address comes back unknown, free.'),
+    },
+    annotations: { title: 'Verify an email address', ...CHECK },
+    call: (args) => request('/v1/email', args),
+  },
+  {
+    name: 'look_up_ip_address',
+    title: 'Look up an IP address',
+    description:
+      'Finds where an IP address is and what network it is on (country, city, ASN and organisation), and whether it ' +
+      'is Tor, a VPN or a datacenter. Charged per check from your balance; the sandbox (a pt_test_ key) is free.',
+    inputSchema: { ip: text(64, IP, true) },
+    annotations: { title: 'Look up an IP address', ...CHECK },
+    call: (args) => request('/v1/ip', args),
+  },
+  {
+    name: 'assess_identity_risk',
+    title: 'Assess the risk of an identity',
+    description:
+      'Scores an identity from 0 (no risk found) to 100 with a verdict (allow, review or deny) and the reasons that ' +
+      'added to the score, from any mix of phone number, email address and IP address, each checked in parallel; ' +
+      'each signal\'s own result is under signals. Give at least one of the three. Charged per signal from your ' +
+      'balance; the sandbox (a pt_test_ key) is free.',
+    inputSchema: {
+      phone: text(32, PHONE),
+      email: text(254, EMAIL),
+      ip: text(64, IP),
+      country,
+      reference: z.string().max(128).optional().describe('Your own id for this check (a sign-up, an order), echoed back.'),
+    },
+    annotations: { title: 'Assess the risk of an identity', ...CHECK },
+    call: (args) => {
+      if (!args.phone && !args.email && !args.ip) {
+        throw new ApiError('Give at least one of a phone number, an email address and an IP address.', { code: 'nothing_to_assess' })
+      }
+      return request('/v1/assess', args)
+    },
+  },
+  {
+    name: 'get_balance',
+    title: "Get the account's balance",
+    description:
+      "The account's balance in US dollars (paid and promotional money, what is held for running files) and what " +
+      "this month's checks cost so far, by signal. Free. Useful before a batch of checks, or to tell a live key " +
+      '(pt_live_) from the sandbox.',
+    inputSchema: {},
+    annotations: { title: "Get the account's balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    call: () => request('/v1/balance'),
+  },
+]
+
+/** The arguments as the api takes them: empty strings dropped, a country upper-cased. */
+function cleaned (args = {}) {
+  const out = {}
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) continue
+    out[key] = typeof value === 'string' ? value.trim() : value
+  }
+  if (out.country) out.country = out.country.toUpperCase()
+  return out
+}
+
+/** Runs a tool and shapes its result for MCP: the answer as JSON text and structured content, or a tool error. */
+export async function run (tool, args) {
+  try {
+    const answer = await tool.call(cleaned(args))
+    return { content: [{ type: 'text', text: JSON.stringify(answer, null, 2) }], structuredContent: answer }
+  } catch (err) {
+    const message = err instanceof ApiError ? err.message : 'The call failed before reaching ProofTell.'
+    const detail = err instanceof ApiError && err.code ? ` (${err.code}${err.status ? `, HTTP ${err.status}` : ''})` : ''
+    return { isError: true, content: [{ type: 'text', text: message + detail }] }
+  }
+}