transparentcars-mcp 0.1.0

package/.well-known/mcp.json

@@ -0,0 +1,21 @@
+{
+  "name": "transparentcars",
+  "description": "Search budget used cars in Portugal, check whether an asking price is fair, estimate a car's yearly running cost, and reach TransparentCars.",
+  "version": "0.1.0",
+  "vendor": "TransparentCars",
+  "homepage": "https://transparent.pt",
+  "documentation": "https://github.com/transparentpt/mcp",
+  "license": "MIT",
+  "transports": {
+    "streamable_http": { "url": "https://transparent.pt/mcp" },
+    "stdio": { "command": "npx", "args": ["-y", "transparentcars-mcp"] }
+  },
+  "tools": [
+    "search_inventory",
+    "get_car",
+    "check_fair_price",
+    "cost_to_own",
+    "list_makes_models",
+    "contact_me"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TransparentCars
+
+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,82 @@
+<p align="center">
+  <img src="./assets/wordmark.png" alt="TransparentCars" width="320" />
+</p>
+
+# TransparentCars MCP server
+
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants work with **[TransparentCars](https://transparent.pt)** — honest, budget used cars for the local Portuguese market. Search live stock, check whether a car's asking price is actually fair, estimate the yearly cost of keeping a car on the road, and get in touch.
+
+It's a thin, open-source wrapper over the public `transparent.pt` API — no keys, no setup beyond adding the server.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_inventory` | Search current budget stock by make, model, fuel, gearbox, price, year |
+| `get_car` | Full details + specs for one car |
+| `check_fair_price` | The market range a car sells for — plus a fair / above-market / below-market verdict on an asking price |
+| `cost_to_own` | The annual IUC road tax + a plain running-cost framing for budgeting |
+| `list_makes_models` | Canonical brand/model names the other tools expect |
+| `contact_me` | Ask a human to get in touch (needs the user's consent + contact) |
+
+The **fair-price check** is the point: paste any listing's price and get a straight answer on whether it's a good deal — no sales spin.
+
+## Use it
+
+### Remote (add a URL)
+
+```
+https://transparent.pt/mcp
+```
+
+Add it in any client that supports remote/Streamable HTTP MCP servers.
+
+### Local (stdio, via npx)
+
+Claude Desktop / Cline / Continue config:
+
+```json
+{
+  "mcpServers": {
+    "transparentcars": {
+      "command": "npx",
+      "args": ["-y", "transparentcars-mcp"]
+    }
+  }
+}
+```
+
+## Examples
+
+- "Find a manual petrol car under €10,000 in TransparentCars stock."
+- "A dealer wants €9,500 for a 2014 Renault Clio with 120,000 km — is that fair?"
+- "What's the yearly road tax on a 2016 petrol, 1200 cc, 120 g/km CO₂?"
+- "Ask TransparentCars to call me — my name is … and my number is …"
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `TC_API_BASE` | `https://transparent.pt/api/public` | Public API base |
+| `TC_SITE` | `transparentcars` | Site key the API is scoped to |
+| `TC_LANG` | `en` | Response language (pt/en) |
+| `PORT` / `MCP_PATH` | `8099` / `/mcp` | HTTP server (remote mode) |
+
+## Develop
+
+```bash
+npm install
+npm run build
+node dist/index.js        # stdio
+npm run start:http        # remote HTTP on :8099/mcp
+```
+
+## Notes
+
+- **Estimates, not guarantees.** The fair-price range and running-cost figures are estimates built from real comparable listings and the official road-tax table; treat them as guidance, not a formal valuation.
+- **Privacy.** `contact_me` sends the details the user provides to TransparentCars ([privacy policy](https://transparent.pt/en/privacy)); it requires explicit user intent and consent.
+- No business logic or data lives in this repo — it only calls the public API.
+
+MIT © TransparentCars

package/dist/api.js

@@ -0,0 +1,45 @@
+// Thin client for the public transparent.pt API. No secrets, no business logic here —
+// everything (inventory, valuation, road tax, leads) lives behind these public endpoints.
+export const API_BASE = process.env.TC_API_BASE?.replace(/\/$/, "") ||
+    "https://transparent.pt/api/public";
+export const SITE = process.env.TC_SITE || "transparentcars";
+export const DEFAULT_LANG = process.env.TC_LANG || "en";
+const UA = "transparentcars-mcp/0.1";
+async function req(path, init) {
+    const url = path.startsWith("http") ? path : `${API_BASE}${path}`;
+    const res = await fetch(url, {
+        ...init,
+        headers: { "user-agent": UA, accept: "application/json", ...(init?.headers || {}) },
+    });
+    const text = await res.text();
+    let data = null;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        data = { raw: text };
+    }
+    if (!res.ok) {
+        const detail = data?.detail || data?.raw || res.statusText;
+        throw new Error(`API ${res.status}: ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
+    }
+    return data;
+}
+export function apiGet(path, params) {
+    const qs = new URLSearchParams();
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== null && v !== "")
+                qs.set(k, String(v));
+        }
+    }
+    const sep = path.includes("?") ? "&" : "?";
+    return req(qs.toString() ? `${path}${sep}${qs}` : path);
+}
+export function apiPost(path, body) {
+    return req(path, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}

package/dist/http.js

@@ -0,0 +1,68 @@
+// TransparentCars MCP server — remote Streamable HTTP transport (for "add a URL" clients).
+// Stateless: a fresh server+transport per request (simple, horizontally scalable).
+import { createServer } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { registerTools } from "./tools.js";
+const PORT = Number(process.env.PORT || 8099);
+const HOST = process.env.MCP_HOST || "127.0.0.1"; // bind loopback; front with an (auth) proxy, never all-interfaces
+const MCP_PATH = process.env.MCP_PATH || "/mcp";
+// Anti-DNS-rebinding: this SDK's StreamableHTTPServerTransport doesn't expose allowedHosts, so gate here.
+const ALLOWED_HOSTS = (process.env.MCP_ALLOWED_HOSTS || "transparent.pt,mcp.transparent.pt,localhost:8099,127.0.0.1:8099")
+    .split(",").map((s) => s.trim().toLowerCase());
+const ALLOWED_ORIGINS = (process.env.MCP_ALLOWED_ORIGINS || "https://transparent.pt")
+    .split(",").map((s) => s.trim());
+function originAllowed(req) {
+    const host = String(req.headers.host || "").toLowerCase();
+    if (!ALLOWED_HOSTS.includes(host))
+        return false; // blocks rebinding to attacker Host
+    const origin = req.headers.origin; // native MCP clients send none → allowed
+    if (origin && !ALLOWED_ORIGINS.includes(origin))
+        return false; // blocks browser cross-origin
+    return true;
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let raw = "";
+        req.on("data", (c) => (raw += c));
+        req.on("end", () => {
+            try {
+                resolve(raw ? JSON.parse(raw) : undefined);
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+    });
+}
+async function handleMcp(req, res) {
+    const server = new McpServer({ name: "transparentcars", version: "0.1.0" });
+    registerTools(server);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        transport.close();
+        server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, await readBody(req));
+}
+createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://${req.headers.host}`);
+    if (url.pathname === "/healthz") {
+        res.writeHead(200, { "content-type": "text/plain" }).end("ok");
+        return;
+    }
+    if (url.pathname === MCP_PATH) {
+        if (!originAllowed(req)) {
+            res.writeHead(403, { "content-type": "text/plain" }).end("forbidden");
+            return;
+        }
+        handleMcp(req, res).catch((e) => {
+            console.error("mcp error", e);
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        });
+        return;
+    }
+    res.writeHead(404).end();
+}).listen(PORT, HOST, () => console.error(`transparentcars-mcp HTTP on ${HOST}:${PORT}${MCP_PATH}`));

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// TransparentCars MCP server — stdio transport (for `npx transparentcars-mcp`, Claude Desktop, Cline, etc.)
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+const server = new McpServer({ name: "transparentcars", version: "0.1.0" });
+registerTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// stderr only — stdout is the MCP channel
+console.error("transparentcars-mcp running on stdio");

package/dist/tools.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { apiGet, apiPost, SITE, DEFAULT_LANG } from "./api.js";
+const SITE_URL = "https://transparent.pt";
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const eur = (n) => (typeof n === "number" ? `€${Math.round(n).toLocaleString("en-US")}` : "—");
+const carUrl = (slug) => `${SITE_URL}/${DEFAULT_LANG}/car/${slug}`;
+export function registerTools(server) {
+    // ---- search_inventory ---------------------------------------------------
+    server.tool("search_inventory", "Search TransparentCars' current stock of budget used cars in Portugal — honestly listed, everyday cars for the local market. Filter by make, model, fuel, gearbox and max price. Returns matching cars with price, year, mileage and a link. IMPORTANT — pass make/model canonically in Latin, as the Portuguese market lists them: make = full brand name ('BMW', 'Mercedes-Benz' not 'Mercedes', 'Volkswagen' not 'VW'); model = the short series/model WITHOUT the engine or trim suffix ('Golf' not 'Golf 1.5 TSI', 'Clio' not 'Clio dCi'). Put the fuel in the fuel field, not the model. If unsure of the spelling, call list_makes_models first.", {
+        make: z.string().optional().describe("Full brand name in Latin, as the market lists it — 'Renault', 'Volkswagen' (not 'VW'), 'Peugeot', 'Seat'."),
+        model: z.string().optional().describe("Short model name WITHOUT engine or trim — 'Clio' (not 'Clio 1.5 dCi'), 'Golf' (not 'Golf TSI')."),
+        fuel: z.string().optional().describe("Fuel: petrol, diesel, hybrid, phev, electric, lpg"),
+        gearbox: z.string().optional().describe("Gearbox: manual or automatic"),
+        max_price: z.number().optional().describe("Maximum price in EUR"),
+        min_year: z.number().optional().describe("Earliest registration year"),
+        limit: z.number().int().min(1).max(50).optional().describe("Max results (default 20)"),
+    }, async (a) => {
+        const params = { site: SITE, lang: DEFAULT_LANG };
+        if (a.make)
+            params.make = a.make;
+        if (a.fuel)
+            params.fuel = a.fuel;
+        if (a.gearbox)
+            params.gearbox = a.gearbox;
+        if (typeof a.max_price === "number")
+            params.max_price = a.max_price;
+        const data = await apiGet("/cars", params);
+        let cars = data?.cars || [];
+        const norm = (s) => String(s || "").toLowerCase();
+        // Client-side narrowing for filters the API doesn't take (model, min_year) and as a safety net.
+        if (a.make)
+            cars = cars.filter((c) => norm(c.make).includes(norm(a.make)));
+        if (a.model)
+            cars = cars.filter((c) => norm(c.model).includes(norm(a.model)));
+        if (a.fuel)
+            cars = cars.filter((c) => norm(c.fuel).includes(norm(a.fuel)) || norm(c.fuel_code).includes(norm(a.fuel)));
+        if (a.gearbox)
+            cars = cars.filter((c) => norm(c.gearbox).includes(norm(a.gearbox)));
+        if (typeof a.max_price === "number")
+            cars = cars.filter((c) => (c.price_eur ?? Infinity) <= a.max_price);
+        if (typeof a.min_year === "number")
+            cars = cars.filter((c) => (c.year ?? 0) >= a.min_year);
+        cars = cars.slice(0, a.limit ?? 20);
+        if (!cars.length)
+            return text("No cars in stock match those filters right now. Try widening the search, or browse everything at " + `${SITE_URL}/${DEFAULT_LANG}/cars`);
+        const lines = cars.map((c) => `• ${c.make} ${c.model} (${c.year || "—"}) — ${eur(c.price_eur)}, ${(c.km ?? 0).toLocaleString("en-US")} km, ${c.fuel || "—"}${c.gearbox ? ", " + c.gearbox : ""}\n  ${carUrl(c.slug)}`);
+        return text(`${cars.length} car(s) in stock:\n\n${lines.join("\n")}`);
+    });
+    // ---- get_car ------------------------------------------------------------
+    server.tool("get_car", "Get full details for one car in TransparentCars stock by its slug (from a search_inventory link, e.g. 'renault-clio-2016').", { slug: z.string().describe("Car slug from a search_inventory result URL") }, async (a) => {
+        const c = await apiGet(`/cars/${encodeURIComponent(a.slug)}`, { site: SITE, lang: DEFAULT_LANG });
+        const specs = [
+            `Price: ${eur(c.price_eur)}`,
+            `Year: ${c.year || "—"}`,
+            `Mileage: ${(c.km ?? 0).toLocaleString("en-US")} km`,
+            `Fuel: ${c.fuel || "—"}`,
+            `Gearbox: ${c.gearbox || "—"}`,
+            `Body: ${c.body || "—"}`,
+            c.hp ? `Power: ${c.hp} hp` : null,
+            c.cc ? `Engine: ${c.cc} cc` : null,
+            c.co2 ? `CO₂: ${c.co2} g/km` : null,
+            c.colour ? `Colour: ${c.colour}` : null,
+        ].filter(Boolean).join("\n");
+        const desc = c.description ? `\n\n${c.description}` : "";
+        return text(`${c.make} ${c.model} (${c.year || "—"})\n${specs}${desc}\n\n${carUrl(c.slug)}`);
+    });
+    // ---- check_fair_price ---------------------------------------------------
+    server.tool("check_fair_price", "Check whether a car's asking price is fair for the Portuguese market — the TransparentCars transparency check. Given make, model, year and mileage, it returns the range comparable cars actually sell for (low / typical / high), built from real listings. If you pass asking_price, it also gives a plain verdict: fair, above market, or below market — so a buyer knows before they walk in. Works for ANY car (a listing you found elsewhere, or one of ours). IMPORTANT — pass make/model canonically in Latin: make = full brand name ('Renault', 'Volkswagen' not 'VW'); model = short name WITHOUT engine/trim ('Clio' not 'Clio dCi', 'Golf' not 'Golf 1.5 TSI'). If unsure of spelling, call list_makes_models first.", {
+        make: z.string().describe("Full brand name in Latin — 'Renault', 'Volkswagen' (not 'VW'), 'Peugeot', 'Seat'."),
+        model: z.string().describe("Short model name WITHOUT engine or trim — 'Clio' (not 'Clio 1.5 dCi'), 'Golf' (not 'Golf TSI')."),
+        year: z.number().int().describe("Registration year"),
+        km: z.number().int().describe("Mileage in km"),
+        fuel: z.string().optional().describe("Fuel: petrol, diesel, hybrid, electric"),
+        gearbox: z.string().optional().describe("Gearbox: manual or automatic"),
+        hp: z.number().int().optional().describe("Power in hp (sharpens the comparison)"),
+        asking_price: z.number().optional().describe("The price being asked for THIS car, in EUR — pass it to get a fair / above-market / below-market verdict."),
+    }, async (a) => {
+        const v = await apiGet("/valuation", {
+            make: a.make, model: a.model, year: a.year, km: a.km,
+            fuel: a.fuel, gearbox: a.gearbox, hp: a.hp,
+        });
+        const carLbl = `${a.make} ${a.model} ${a.year}, ${a.km.toLocaleString("en-US")} km`;
+        if (!v?.found)
+            return text(`Not enough comparable listings to price that ${a.make} ${a.model} automatically right now. ` +
+                `Try again without the fuel/gearbox filters, or ask us to look manually via contact_me.`);
+        const rough = v.rough ? " (rough — few comparables)" : "";
+        const lines = [
+            `Fair-price check for ${carLbl}${rough}:`,
+            `• Typical (market): ${eur(v.median)}`,
+            `• Fair range: ${eur(v.low)} – ${eur(v.high)}`,
+            v.days_sell ? `• Avg. time to sell: ~${v.days_sell} days` : null,
+            `Based on ${v.comps} comparable listing(s) — the range similar cars actually go for.`,
+        ].filter(Boolean);
+        if (typeof a.asking_price === "number") {
+            const ask = a.asking_price;
+            let verdict;
+            if (ask <= v.low) {
+                const under = Math.round(((v.median - ask) / v.median) * 100);
+                verdict = `Asking ${eur(ask)} → BELOW MARKET. That's under the fair range${under > 0 ? ` (~${under}% below typical)` : ""}. Good on price — check why it's cheap (condition, history, mileage), but the number itself is buyer-friendly.`;
+            }
+            else if (ask >= v.high) {
+                const over = Math.round(((ask - v.median) / v.median) * 100);
+                verdict = `Asking ${eur(ask)} → ABOVE MARKET. That's over the fair range${over > 0 ? ` (~${over}% above typical)` : ""}. There's room to negotiate down, or the seller should justify the premium (low km, full history, extras).`;
+            }
+            else {
+                verdict = `Asking ${eur(ask)} → FAIR. It sits inside the range comparable cars sell for. A reasonable ask — small negotiation room as always.`;
+            }
+            lines.push("", verdict);
+        }
+        else {
+            lines.push("", "Pass asking_price to get a fair / above-market / below-market verdict on a specific listing.");
+        }
+        return text(lines.join("\n"));
+    });
+    // ---- cost_to_own --------------------------------------------------------
+    server.tool("cost_to_own", "Estimate a car's yearly running-cost floor in Portugal — the annual IUC road tax (Imposto Único de Circulação) every owner pays, plus a plain running-cost framing. Needs engine displacement (cc), CO₂ (g/km), fuel and first-registration year. Use this to help a buyer budget the true cost of keeping a car, beyond the sticker price.", {
+        cc: z.number().int().describe("Engine displacement in cm³, e.g. 1200"),
+        co2: z.number().describe("CO₂ emissions in g/km, e.g. 120"),
+        fuel: z.string().describe("Fuel: petrol, diesel, hybrid, phev, electric, lpg"),
+        year: z.number().int().describe("First registration year, e.g. 2016"),
+        month: z.number().int().min(1).max(12).optional().describe("First-registration month (1-12), refines the CO₂ regime"),
+        used: z.boolean().optional().describe("Used vehicle (true, default)"),
+    }, async (a) => {
+        const r = await apiGet("/isv", {
+            cc: a.cc, co2: a.co2, fuel: a.fuel, year: a.year,
+            month: a.month, used: a.used === false ? 0 : 1,
+        });
+        const iuc = r?.iuc;
+        if (!iuc || typeof iuc.iuc !== "number")
+            return text(`Couldn't work out the road tax for those inputs. Double-check cc, CO₂ and year.`);
+        if (iuc.exempt)
+            return text(`Annual road tax (IUC): €0/year — exempt.${iuc.note ? " " + iuc.note : ""}\n\nSo the yearly tax floor on this car is nothing; you'd still budget insurance, inspection (IPO) and servicing.`);
+        const annual = iuc.iuc;
+        const parts = [
+            `Annual road tax (IUC): ${eur(annual)}/year`,
+            typeof iuc.taxa_cilindrada === "number" ? `  engine component: ${eur(iuc.taxa_cilindrada)}` : null,
+            typeof iuc.taxa_co2 === "number" && iuc.taxa_co2 ? `  CO₂ component: ${eur(iuc.taxa_co2)}` : null,
+            typeof iuc.diesel_adic === "number" && iuc.diesel_adic ? `  diesel component: ${eur(iuc.diesel_adic)}` : null,
+        ].filter(Boolean);
+        const framing = `\n\nThat IUC is the guaranteed yearly cost just to keep it road-legal (~${eur(Math.round(annual / 12))}/month). ` +
+            `On top of it, budget insurance, the annual IPO inspection and routine servicing — the real cost of owning the car, not just buying it.` +
+            `${iuc.note ? "\n" + iuc.note : ""}\n\nEstimate from the official IUC table; confirm the exact figure with Finanças.`;
+        return text(parts.join("\n") + framing);
+    });
+    // ---- list_makes_models -------------------------------------------------
+    server.tool("list_makes_models", "List the exact canonical car makes (brands) TransparentCars can search and price — or, given a make, that brand's models — using the exact strings the other tools expect. Call this FIRST (or whenever unsure of spelling) and pass the returned values verbatim into search_inventory / check_fair_price. No make = the list of brands; with a make = that brand's models.", { make: z.string().optional().describe("Brand to list models for, e.g. 'Renault'. Omit to get the list of brands.") }, async (a) => {
+        const r = await apiGet("/car_refs", a.make ? { make: a.make } : {});
+        if (!a.make) {
+            const makes = r?.makes || [];
+            return text(makes.length ? `Available makes (pass one of these EXACTLY as 'make'):\n${makes.join(", ")}` : "Couldn't load the make list right now.");
+        }
+        const models = r?.models || [];
+        return text(models.length
+            ? `Models for ${r.make} (pass one of these EXACTLY as 'model'):\n${models.join(", ")}`
+            : `No models found for '${a.make}'. Check the make spelling by calling list_makes_models with no argument.`);
+    });
+    // ---- contact_me ---------------------------------------------------------
+    server.tool("contact_me", "Send a contact request to TransparentCars so a human gets in touch. Only call this when the user explicitly asks to be contacted, provides their own name and a phone or email, AND agrees to share those details — pass consent=true only then. Submitting shares the provided contact details per the TransparentCars privacy policy.", {
+        name: z.string().describe("The person's name (as they gave it)"),
+        contact: z.string().describe("A phone number or email where they can be reached"),
+        message: z.string().optional().describe("What they want / their question"),
+        consent: z.boolean().describe("Set true ONLY if the user explicitly agreed to share their contact details and be contacted"),
+    }, async (a) => {
+        if (!a.consent)
+            return text("Before sending, the user must explicitly agree to share their contact details with TransparentCars. Confirm consent, then call again with consent=true.");
+        if (!a.contact || !a.contact.trim())
+            return text("A phone number or email is required to send a contact request. Ask the user for one.");
+        const val = a.contact.trim();
+        const isEmail = val.includes("@");
+        const r = await apiPost("/lead", {
+            kind: "contact",
+            name: a.name,
+            email: isEmail ? val : undefined,
+            phone: isEmail ? undefined : val,
+            message: a.message,
+            lang: DEFAULT_LANG,
+            source: "mcp",
+            consent: true,
+        });
+        if (r?.duplicate)
+            return text("You already sent this request — TransparentCars has it and will be in touch.");
+        return text("Sent ✓ TransparentCars received your request and will contact you soon.");
+    });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "transparentcars-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.transparentpt/mcp",
+  "description": "MCP server for TransparentCars — search budget used cars in Portugal, check whether an asking price is fair, estimate a car's yearly running cost, and get in touch. Thin wrapper over the public transparent.pt API.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "transparentcars-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    ".well-known"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cars",
+    "portugal",
+    "used-cars",
+    "budget-cars",
+    "automotive"
+  ],
+  "homepage": "https://transparent.pt",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/transparentpt/mcp"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}