atheris-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arvane Holdings OÜ (atheris.ee)
+
+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,91 @@
+<!-- SOURCE OF TRUTH: this monorepo mcp/ directory. Any change to atheris-mcp.mjs
+     or this README must be pushed to the public mirror (github.com/atheris-ee/
+     atheris-mcp) and, if the server changed, published to npm as atheris-mcp. -->
+# atheris-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [Atheris](https://atheris.ee)
+proxies — real-carrier 4G/5G mobile and residential IPs, per gigabyte. It gives an
+agent a fully autonomous path to route traffic through a specific-country IP: check
+live stock, get a ready-to-use proxy URL, and check remaining GB — all as tool calls.
+
+Zero dependencies. One file. Node ≥ 18.
+
+## Tools
+
+- **`atheris_stock`** — live proxy stock by country and pool (`mbl` = mobile,
+  `peer` = residential). No key needed. Call it first to pick a country with capacity.
+- **`atheris_proxy_url`** — a ready `http://` or `socks5://` proxy URL for a
+  country/pool/session/rotation. Hand it straight to any HTTP client.
+- **`atheris_usage`** — the key's remaining GB and expiry.
+
+## Setup
+
+You need an Atheris access key (`pak_…`) from the [dashboard](https://atheris.ee/dashboard).
+
+Straight from GitHub (no install):
+
+```jsonc
+// Claude Desktop / Claude Code / Cursor / any MCP client
+{
+  "mcpServers": {
+    "atheris": {
+      "command": "npx",
+      "args": ["-y", "github:atheris-ee/atheris-mcp"],
+      "env": { "ATHERIS_PROXY_KEY": "pak_your_key_here" }
+    }
+  }
+}
+```
+
+Or from a local checkout:
+
+```jsonc
+{
+  "mcpServers": {
+    "atheris": {
+      "command": "node",
+      "args": ["/path/to/atheris-mcp.mjs"],
+      "env": { "ATHERIS_PROXY_KEY": "pak_your_key_here" }
+    }
+  }
+}
+```
+
+Env:
+- `ATHERIS_PROXY_KEY` — your pak access key (required for `atheris_proxy_url`
+  and `atheris_usage`; `atheris_stock` works without it).
+- `ATHERIS_API_BASE` — defaults to `https://atheris.ee/api/v1`. Your key is sent
+  as a Bearer token to whatever host this names, so only point it at a host you
+  trust.
+
+The key is the same credential used as the proxy password — treat it like one.
+Keep it in `env`, not in command args, and rotate it from the dashboard if it
+leaks. The server talks only to `atheris.ee` (or your `ATHERIS_API_BASE`) and
+collects no telemetry.
+
+**The `atheris_proxy_url` result is also a secret.** Both its `proxy_url` and
+`password` fields embed your pak key — treat the tool's output like the key
+itself: don't log it or paste it into shared transcripts.
+
+## Session rule (important)
+
+Each `atheris_proxy_url` call takes a `session` id. **The same session id returns the
+same exit IP.** For many parallel identities (scraping distinct hosts, running many
+antidetect profiles), give each identity its own session id — reusing one sticky
+session across many pins them all to a single exit. Use `rotation: "hard"` if you want
+a fresh exit on every connection instead.
+
+## The underlying HTTP API
+
+The server is a thin wrapper over the Atheris JSON API (bearer-authed with your pak key):
+
+- `GET /api/v1/stock`
+- `GET /api/v1/proxy?country=us&pool=mbl&session=<id>&rotation=sticky&protocol=http`
+- `GET /api/v1/usage`
+
+See <https://atheris.ee/llms-full.txt> for the full agent reference, including
+buying access programmatically.
+
+## License
+
+MIT © [Arvane Holdings OÜ](https://atheris.ee)

package/atheris-mcp.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Atheris MCP server — exposes the Atheris proxy API as MCP tools so any
+ * MCP-capable agent can pick a country with live stock, get a ready proxy URL,
+ * and check its remaining GB. Zero dependencies (JSON-RPC 2.0 over stdio, node
+ * global fetch).
+ *
+ * Env:
+ *   ATHERIS_PROXY_KEY   your pak_ access key (required for proxy_url + usage)
+ *   ATHERIS_API_BASE    default https://atheris.ee/api/v1
+ *
+ * Run:  ATHERIS_PROXY_KEY=pak_... node mcp/atheris-mcp.mjs
+ */
+const API = (process.env.ATHERIS_API_BASE || "https://atheris.ee/api/v1").replace(/\/$/, "");
+const KEY = process.env.ATHERIS_PROXY_KEY || "";
+const PROTOCOL = "2025-06-18";
+const UA = "atheris-mcp/0.1.1";
+const TIMEOUT_MS = 20_000;
+
+const TOOLS = [
+  {
+    name: "atheris_stock",
+    description:
+      "List live Atheris proxy stock by country and pool (mbl = mobile 4G/5G, peer = residential). No key required. Call this before atheris_proxy_url to pick a country that has capacity.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "atheris_proxy_url",
+    description:
+      "Get a ready-to-use Atheris proxy URL for a country. Returns an http:// or socks5:// URL you can hand to any HTTP client. Requires ATHERIS_PROXY_KEY. NOTE: the returned proxy_url and password embed your pak_ key — treat the result as a secret; do not log it or echo it into transcripts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        country: { type: "string", description: "lowercase ISO code, e.g. us, gb, nl, br" },
+        pool: { type: "string", enum: ["mbl", "peer"], description: "mbl=mobile, peer=residential (default mbl)" },
+        session: { type: "string", description: "session id [a-z0-9_]{1,64}; SAME id = SAME exit IP. Use a distinct id per identity." },
+        rotation: { type: "string", description: "sticky | sticky-strict | auto5 | auto10 | auto20 | auto30 | auto60 | hard | ondemand (default sticky)" },
+        protocol: { type: "string", enum: ["http", "socks5"], description: "default http" },
+        carrier: { type: "string", description: "optional mobile carrier, e.g. tmobile, orange" },
+        city: { type: "string", description: "optional city, lowercase (availability varies by country/pool)" },
+      },
+      required: ["country"],
+    },
+  },
+  {
+    name: "atheris_usage",
+    description: "Check the access key's remaining GB and expiry. Requires ATHERIS_PROXY_KEY.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function apiGet(path, auth) {
+  const headers = { "user-agent": UA };
+  if (auth) headers.authorization = `Bearer ${KEY}`;
+  let res;
+  try {
+    res = await fetch(`${API}${path}`, { headers, signal: AbortSignal.timeout(TIMEOUT_MS) });
+  } catch (e) {
+    // Never let an upstream hang or network error wedge the MCP client — a
+    // tool call must always resolve. TimeoutError fires at TIMEOUT_MS.
+    const reason = e?.name === "TimeoutError" ? `timed out after ${TIMEOUT_MS}ms` : (e?.message ?? String(e));
+    return { ok: false, status: 0, json: { error: `request failed: ${reason}` } };
+  }
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = { error: `non-JSON response (${res.status})`, body: text.slice(0, 200) };
+  }
+  return { ok: res.ok, status: res.status, json };
+}
+
+async function callTool(name, args = {}) {
+  if ((name === "atheris_proxy_url" || name === "atheris_usage") && !KEY) {
+    return { isError: true, text: "ATHERIS_PROXY_KEY is not set — required for this tool." };
+  }
+  if (name === "atheris_stock") {
+    const r = await apiGet("/stock", false);
+    return { isError: !r.ok, text: JSON.stringify(r.json, null, 2) };
+  }
+  if (name === "atheris_usage") {
+    const r = await apiGet("/usage", true);
+    return { isError: !r.ok, text: JSON.stringify(r.json, null, 2) };
+  }
+  if (name === "atheris_proxy_url") {
+    const q = new URLSearchParams();
+    for (const k of ["country", "pool", "session", "rotation", "protocol", "carrier", "city"]) {
+      if (args[k]) q.set(k, String(args[k]));
+    }
+    const r = await apiGet(`/proxy?${q.toString()}`, true);
+    return { isError: !r.ok, text: JSON.stringify(r.json, null, 2) };
+  }
+  return { isError: true, text: `unknown tool: ${name}` };
+}
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+const err = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    return ok(id, {
+      protocolVersion: params?.protocolVersion || PROTOCOL,
+      capabilities: { tools: {} },
+      serverInfo: { name: "atheris-mcp", version: "0.1.1" },
+    });
+  }
+  if (method === "notifications/initialized" || method === "notifications/cancelled") return; // notification, no reply
+  if (method === "ping") return ok(id, {});
+  if (method === "tools/list") return ok(id, { tools: TOOLS });
+  if (method === "tools/call") {
+    const { name, arguments: args } = params || {};
+    try {
+      const r = await callTool(name, args);
+      return ok(id, { content: [{ type: "text", text: r.text }], isError: r.isError });
+    } catch (e) {
+      return ok(id, { content: [{ type: "text", text: `error: ${e?.message ?? e}` }], isError: true });
+    }
+  }
+  if (id !== undefined) return err(id, -32601, `method not found: ${method}`);
+}
+
+let buf = "";
+const inFlight = new Set();
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const p = handle(msg).catch(() => {});
+    inFlight.add(p);
+    p.finally(() => inFlight.delete(p));
+  }
+});
+// Drain in-flight tool calls before exiting — a client (or one-shot pipe)
+// that closes stdin right after a request must still get its reply.
+process.stdin.on("end", () => {
+  Promise.allSettled([...inFlight]).then(() => process.exit(0));
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "atheris-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for Atheris proxies — live stock, ready proxy URLs, and usage, as tools for any MCP-capable agent.",
+  "type": "module",
+  "bin": {
+    "atheris-mcp": "./atheris-mcp.mjs"
+  },
+  "files": [
+    "atheris-mcp.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atheris-ee/atheris-mcp.git"
+  },
+  "homepage": "https://atheris.ee",
+  "mcpName": "io.github.atheris-ee/atheris-mcp",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "proxy",
+    "mobile-proxy",
+    "residential-proxy",
+    "ai-agents",
+    "atheris"
+  ]
+}