mcp-server-auction 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,106 @@
+# MCP Server Auction
+
+MCP server for dedicated server auctions and listings. Enables LLMs to search, filter, and analyze real-time dedicated server listings from multiple providers through a unified interface.
+
+[![npm version](https://img.shields.io/npm/v/mcp-server-auction)](https://www.npmjs.com/package/mcp-server-auction)
+[![CI](https://github.com/raws-labs/mcp-server-auction/actions/workflows/ci.yml/badge.svg)](https://github.com/raws-labs/mcp-server-auction/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Multi-provider** — Hetzner Server Auction + OVH ECO in a single interface
+- **14+ filter parameters** — price, RAM, disk type/size/count, CPU vendor/model/cores, ECC, GPU, datacenter, bandwidth, and more
+- **Real-time data** — fetches live listings directly from provider APIs
+- **No auth required** — all upstream APIs are public
+- **Stdio transport** — works with any MCP-compatible client
+
+## Installation
+
+```bash
+npm install -g mcp-server-auction
+```
+
+Or run directly with npx:
+
+```bash
+npx mcp-server-auction
+```
+
+## Configuration
+
+The server communicates over stdio using the Model Context Protocol. Point your MCP client at the binary:
+
+```bash
+mcp-server-auction
+```
+
+## Tools
+
+### `search_auctions`
+
+Search and filter dedicated server auction listings by price, RAM, disk, CPU, datacenter, GPU, bandwidth, and more.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `provider` | `"hetzner" \| "ovh" \| "all"` | Provider filter (default: `"all"`) |
+| `max_price` | `number` | Maximum monthly price in EUR |
+| `min_ram` | `number` | Minimum RAM in GB |
+| `min_disk_size` | `number` | Minimum total disk capacity in GB |
+| `min_disk_count` | `number` | Minimum number of disks |
+| `disk_type` | `"ssd" \| "nvme" \| "hdd" \| "any"` | Filter by disk type (`ssd` matches both SATA SSD and NVMe) |
+| `cpu_vendor` | `"intel" \| "amd" \| "any"` | CPU vendor filter |
+| `cpu_search` | `string` | Free-text search within CPU model name (e.g. `"EPYC 7502"`, `"Xeon E5"`) |
+| `min_cpu_count` | `number` | Minimum CPU/socket count |
+| `min_cores` | `number` | Minimum total CPU cores (accounts for multi-socket) |
+| `ecc` | `boolean` | Require ECC RAM |
+| `datacenter` | `string` | Datacenter filter (e.g. `FSN`, `NBG`, `HEL`, `FRA`, `GRA`) |
+| `gpu` | `boolean` | Require GPU |
+| `min_bandwidth` | `number` | Minimum bandwidth in Mbit (e.g. `1000` = 1 Gbit) |
+| `fixed_price` | `boolean` | `true` = fixed price only, `false` = auction only |
+| `max_setup_price` | `number` | Maximum setup price in EUR (use `0` for no setup fee) |
+| `highio` | `boolean` | Require high I/O hardware |
+| `sort_by` | `"price" \| "ram" \| "disk_size" \| "cpu" \| "cores"` | Sort field (default: `"price"`) |
+| `limit` | `number` | Max results, 1–50 (default: `10`) |
+
+### `get_auction_stats`
+
+Get aggregate statistics about current server auction listings: provider breakdown, price range, CPU vendor split, datacenter distribution, RAM tiers, GPU/ECC counts.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `provider` | `"hetzner" \| "ovh" \| "all"` | Provider filter (default: `"all"`) |
+
+### `get_auction_server`
+
+Get full details of a specific auction server by its ID.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `server_id` | `string` | The server ID (numeric for Hetzner, FQN for OVH) |
+| `provider` | `"hetzner" \| "ovh" \| "all"` | Provider filter (default: `"all"`) |
+
+## Providers
+
+| Provider | Regions | Pricing | Auth |
+|---|---|---|---|
+| **Hetzner** | FSN, NBG (Germany), HEL (Finland) | Auction + fixed | None |
+| **OVH ECO** | FRA (Germany), GRA, RBX, SBG (France), LON (UK), WAW (Poland), BHS (Canada) | Fixed | None |
+
+## Development
+
+```bash
+npm install          # install dependencies
+npm run build        # compile TypeScript → build/
+npm start            # run the server (stdio)
+npm test             # run tests
+```
+
+Inspect interactively with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector build/index.js
+```
+
+## License
+
+[MIT](LICENSE)

package/build/providers/hetzner.js

@@ -39,7 +39,7 @@ function getCountry(dc) {
         return "FI";
     return "DE";
 }
-function buildDisks(d) {
+export function buildDisks(d) {
     const disks = [];
     const addGroup = (sizes, type) => {
         const groups = new Map();
@@ -56,7 +56,7 @@ function buildDisks(d) {
     addGroup(d.general, "unknown");
     return disks;
 }
-function normalizeServer(server, cores) {
+export function normalizeServer(server, cores) {
     const disks = buildDisks(server.serverDiskData);
     return {
         id: String(server.id),
@@ -93,7 +93,7 @@ function normalizeServer(server, cores) {
 // ---------- CPU core resolution ----------
 // Hetzner doesn't include core counts in its API, so we resolve them
 // via a static lookup table + GitHub CSV fallback.
-const KNOWN_CORES = {
+export const KNOWN_CORES = {
     "AMD EPYC 7401P": 24,
     "AMD EPYC 7502": 32,
     "AMD EPYC 7502P": 32,
@@ -124,19 +124,19 @@ const KNOWN_CORES = {
     "Intel Xeon W-2295": 18,
     "Intel Xeon Gold 5412U": 24,
 };
-function normaliseCpuName(name) {
+export function normaliseCpuName(name) {
     return name
         .replace(/[®™]/g, "")
         .replace(/\s+/g, " ")
         .trim()
         .toLowerCase();
 }
-function extractModelToken(name) {
+export function extractModelToken(name) {
     const cleaned = normaliseCpuName(name);
     const m = cleaned.match(/(?:i[3579]-\d{4,5}[a-z]*|e[35]-\d{4}\s*v?\d*|e-\d{4}[a-z]*|w-\d{4,5}[a-z]*|gold \d{4}[a-z]*|epyc \d{4}[a-z]*|ryzen \d+ (?:pro )?\d{4}[a-z]*|threadripper \d{4,5}[a-z]*)/);
     return m ? m[0] : null;
 }
-function parseCsvRow(line) {
+export function parseCsvRow(line) {
     const fields = [];
     let current = "";
     let inQuotes = false;
@@ -216,7 +216,7 @@ async function fetchCsvCoreMap() {
     csvCache = { map, timestamp: Date.now() };
     return map;
 }
-async function resolveCpuCores(cpuName) {
+export async function resolveCpuCores(cpuName) {
     if (cpuName in KNOWN_CORES)
         return KNOWN_CORES[cpuName];
     const norm = normaliseCpuName(cpuName);

package/build/providers/ovh.js

@@ -40,14 +40,14 @@ const DC_COUNTRY = {
     waw: "PL",
     bhs: "CA",
 };
-function dcToCountry(dc) {
+export function dcToCountry(dc) {
     const prefix = dc.replace(/\d+$/, "").toLowerCase();
     return DC_COUNTRY[prefix] ?? "FR";
 }
-function dcToRegion(dc) {
+export function dcToRegion(dc) {
     return dc.replace(/\d+$/, "").toUpperCase();
 }
-function parseMemoryCode(code) {
+export function parseMemoryCode(code) {
     // e.g. "ram-32g-ecc-3200", "ram-64g-noecc-2400"
     const match = code.match(/ram-(\d+)g/i);
     if (!match)
@@ -57,7 +57,7 @@ function parseMemoryCode(code) {
         is_ecc: code.toLowerCase().includes("ecc") && !code.toLowerCase().includes("noecc"),
     };
 }
-function parseStorageCode(code) {
+export function parseStorageCode(code) {
     // e.g. "softraid-2x512nvme", "softraid-2x2000sa", "softraid-4x960ssd"
     // Also handle "raid" variants: "raid1-2x512nvme"
     const match = code.match(/(\d+)x(\d+)(nvme|ssd|sa|hdd)/i);
@@ -74,7 +74,7 @@ function parseStorageCode(code) {
     return [{ count, size_gb: size, type }];
 }
 // ---------- Price normalization ----------
-function extractMonthlyPrice(plan) {
+export function extractMonthlyPrice(plan) {
     // Look for monthly renew pricing
     const renew = plan.pricings.find((p) => p.capacities.includes("renew") && (p.interval === 1 || p.interval === undefined));
     if (!renew)
@@ -86,7 +86,7 @@ function extractMonthlyPrice(plan) {
         return renew.price / 100;
     return priceEur;
 }
-function extractSetupPrice(plan) {
+export function extractSetupPrice(plan) {
     const install = plan.pricings.find((p) => p.capacities.includes("installation"));
     if (!install)
         return 0;
@@ -96,7 +96,7 @@ function extractSetupPrice(plan) {
     return priceEur;
 }
 // ---------- Normalization ----------
-function buildListing(entry, cpuInfo, pricing, planName, availableDcs) {
+export function buildListing(entry, cpuInfo, pricing, planName, availableDcs) {
     const mem = parseMemoryCode(entry.memory);
     const disks = parseStorageCode(entry.storage);
     const cpuName = cpuInfo

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-server-auction",
-  "version": "0.2.0",
-  "description": "MCP server for European dedicated server auctions and listings",
+  "version": "0.2.1",
+  "description": "MCP server for dedicated server auctions and listings",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -13,6 +13,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -37,7 +38,8 @@
   },
   "devDependencies": {
     "typescript": "^5.8.3",
-    "@types/node": "^22.15.3"
+    "@types/node": "^22.15.3",
+    "vitest": "^3.1.0"
   },
   "license": "MIT"
 }