tokengratis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raymond Chin
+
+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,120 @@
+# tokengratis
+
+CLI + MCP server for [tokengratis.id](https://tokengratis.id) — the
+aggregator directory of free-tier & free-credit LLM APIs for Indonesian
+developers.
+
+Zero runtime dependencies. Plain Node ESM (`node >= 20`). Fetches the live
+directory at request time — no bundled/stale copy shipped in this package.
+
+**tokengratis.id is an aggregator, not a verifier.** Every provider and every
+answer from this tool carries provenance (`sources[]` + `syncedAt`) — where
+the data came from and when it was last synced. You will never see the word
+"Verified" here.
+
+## Data source
+
+1. Primary: `https://tokengratis.id/api/providers`
+2. Fallback (if the API is unreachable): `https://raw.githubusercontent.com/raymondchins/tokengratis-id/main/data/providers.json`
+
+Responses are cached in memory for the process and to a short-TTL (1 hour)
+file in the OS temp dir, so repeated CLI invocations don't re-fetch every
+time.
+
+## Install
+
+Not yet published to npm. Until it is, run it straight from the repo (see
+[Running from source](#running-from-source) below), or once published:
+
+```bash
+npm install -g tokengratis
+# or run one-off without installing:
+npx -y tokengratis list
+```
+
+## CLI usage
+
+```
+tokengratis list [--modality <m>] [--min-context <ctx>] [--json]
+tokengratis show <slug> [--json]
+tokengratis search <query> [--json]
+tokengratis models [--provider <slug>] [--json]
+tokengratis --help
+tokengratis --version
+```
+
+Examples:
+
+```bash
+tokengratis list
+tokengratis list --modality vision
+tokengratis list --min-context 128K --json
+tokengratis show openrouter
+tokengratis search llama
+tokengratis models --provider groq
+```
+
+- Plain text output by default; add `--json` to any command for
+  machine-readable output.
+- Color is auto-disabled when stdout isn't a TTY, or when `NO_COLOR` is set.
+- Exits non-zero on error (bad slug, network failure, etc.) with a
+  human-readable message — never a raw stack trace.
+
+## MCP server usage
+
+`tokengratis-mcp` speaks the Model Context Protocol over stdio
+(newline-delimited JSON-RPC 2.0), implemented by hand with no SDK. It
+exposes four tools:
+
+- `list_providers` — optional `modality` / `min_context` filters
+- `get_provider` — full detail for one provider by `slug`, incl. provenance
+- `search_models` — substring search across provider/model names and ids
+- `list_models` — flat model list, optional `provider` slug scope
+
+### Claude Code / Cursor config
+
+Once published to npm:
+
+```json
+{
+  "mcpServers": {
+    "tokengratis": {
+      "command": "npx",
+      "args": ["-y", "-p", "tokengratis", "tokengratis-mcp"]
+    }
+  }
+}
+```
+
+> `tokengratis-mcp` is a **bin inside** the `tokengratis` package, not a package
+> of its own — hence `-p tokengratis`. Plain `npx -y tokengratis-mcp` would try
+> to fetch a package by that name and fail.
+
+### Running from source (works today, package isn't published yet)
+
+Clone the repo, then point your MCP client straight at the local file with
+plain `node` — no install step needed since there are zero dependencies:
+
+```json
+{
+  "mcpServers": {
+    "tokengratis": {
+      "command": "node",
+      "args": ["/absolute/path/to/tokengratis-id/packages/tokengratis/src/mcp-server.mjs"]
+    }
+  }
+}
+```
+
+(Swap `/absolute/path/to/tokengratis-id` for wherever you cloned
+`https://github.com/raymondchins/tokengratis-id`.)
+
+Same trick works for the CLI without installing:
+
+```bash
+node /absolute/path/to/tokengratis-id/packages/tokengratis/src/cli.mjs list
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "tokengratis",
+  "version": "0.1.0",
+  "description": "CLI + MCP server for tokengratis.id, the aggregator directory of free-tier & free-credit LLM APIs for Indonesian developers. Zero runtime dependencies.",
+  "keywords": [
+    "tokengratis",
+    "llm",
+    "free-tier",
+    "free-llm",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "openrouter",
+    "indonesia"
+  ],
+  "license": "MIT",
+  "author": "Raymond Chin",
+  "homepage": "https://tokengratis.id",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raymondchins/tokengratis-id",
+    "directory": "packages/tokengratis"
+  },
+  "bugs": {
+    "url": "https://github.com/raymondchins/tokengratis-id/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "tokengratis": "./src/cli.mjs",
+    "tokengratis-mcp": "./src/mcp-server.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// tokengratis — CLI for the tokengratis.id free-tier LLM API directory.
+// Zero dependencies, plain Node ESM.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getProviders, DataFetchError } from "./lib/data.mjs";
+import { filterByModality, filterByMinContext, searchProviders, listModels } from "./lib/filters.mjs";
+import { createColorizer } from "./lib/color.mjs";
+import {
+  formatProviderListText,
+  formatProviderText,
+  formatModelListText,
+  formatSearchResultsText,
+} from "./lib/render.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+
+const HELP = `tokengratis v${pkg.version} — CLI direktori free-tier LLM API (tokengratis.id)
+
+Usage:
+  tokengratis list [--modality <m>] [--min-context <ctx>] [--json]
+  tokengratis show <slug> [--json]
+  tokengratis search <query> [--json]
+  tokengratis models [--provider <slug>] [--json]
+  tokengratis --help
+  tokengratis --version
+
+Contoh:
+  tokengratis list
+  tokengratis list --modality vision
+  tokengratis list --min-context 128K --json
+  tokengratis show openrouter
+  tokengratis search llama
+  tokengratis models --provider groq
+
+Data live dari https://tokengratis.id/api/providers
+(fallback otomatis ke GitHub raw kalau API down). Cached lokal ~1 jam.
+
+Ini AGGREGATOR, bukan verifier — tiap provider bawa provenance
+(sources[] + syncedAt), transparan apa adanya dari sumber.`;
+
+function getFlagValue(args, name) {
+  const idx = args.indexOf(name);
+  if (idx === -1 || idx === args.length - 1) return undefined;
+  return args[idx + 1];
+}
+
+/** Remove known flags (with or without a value) from an args array, leaving positionals. */
+function positionals(args, valueFlags) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (valueFlags.includes(a)) {
+      i++; // skip its value
+      continue;
+    }
+    if (a === "--json") continue;
+    if (a.startsWith("--")) continue; // unknown flag, ignore rather than crash
+    out.push(a);
+  }
+  return out;
+}
+
+async function cmdList(args, { json, color }) {
+  const modality = getFlagValue(args, "--modality");
+  const minContext = getFlagValue(args, "--min-context");
+  const { providers } = await getProviders();
+
+  let list = providers;
+  list = filterByModality(list, modality);
+  list = filterByMinContext(list, minContext);
+
+  if (json) {
+    console.log(JSON.stringify(list, null, 2));
+    return;
+  }
+  if (list.length === 0) {
+    console.log(formatProviderListText(list, { color }));
+    return;
+  }
+  console.log(formatProviderListText(list, { color }));
+  console.log("");
+  console.log(color.dim(`${list.length} provider. Detail: tokengratis show <slug>`));
+}
+
+async function cmdShow(args, { json, color }) {
+  const [slug] = positionals(args, ["--modality", "--min-context", "--provider"]);
+  if (!slug) {
+    console.error("Error: slug wajib diisi. Contoh: tokengratis show openrouter");
+    process.exitCode = 1;
+    return;
+  }
+  const { providers } = await getProviders();
+  const p = providers.find((x) => x.slug === slug);
+  if (!p) {
+    console.error(`Error: provider dengan slug "${slug}" tidak ditemukan. Coba: tokengratis list`);
+    process.exitCode = 1;
+    return;
+  }
+  if (json) {
+    console.log(JSON.stringify(p, null, 2));
+    return;
+  }
+  console.log(formatProviderText(p, { color }));
+}
+
+async function cmdSearch(args, { json, color }) {
+  const query = positionals(args, ["--modality", "--min-context", "--provider"]).join(" ").trim();
+  if (!query) {
+    console.error('Error: query wajib diisi. Contoh: tokengratis search "llama"');
+    process.exitCode = 1;
+    return;
+  }
+  const { providers } = await getProviders();
+  const results = searchProviders(providers, query);
+  if (json) {
+    console.log(
+      JSON.stringify(
+        results.map((r) => ({
+          slug: r.provider.slug,
+          name: r.provider.name,
+          providerMatch: r.providerMatch,
+          matchedModels: r.matchedModels,
+        })),
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(formatSearchResultsText(results, query, { color }));
+}
+
+async function cmdModels(args, { json, color }) {
+  const providerSlug = getFlagValue(args, "--provider");
+  const { providers } = await getProviders();
+  const rows = listModels(providers, providerSlug);
+  if (json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  console.log(formatModelListText(rows, { color }));
+  console.log("");
+  console.log(color.dim(`${rows.length} model.`));
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(pkg.version);
+    return;
+  }
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  const [command, ...rest] = args;
+  const json = args.includes("--json");
+  const color = createColorizer();
+
+  switch (command) {
+    case "list":
+      await cmdList(rest, { json, color });
+      break;
+    case "show":
+      await cmdShow(rest, { json, color });
+      break;
+    case "search":
+      await cmdSearch(rest, { json, color });
+      break;
+    case "models":
+      await cmdModels(rest, { json, color });
+      break;
+    default:
+      console.error(`Perintah tidak dikenal: "${command}"\n`);
+      console.error(HELP);
+      process.exitCode = 1;
+  }
+}
+
+main(process.argv).catch((err) => {
+  if (err instanceof DataFetchError) {
+    console.error(`Error: ${err.message}`);
+  } else {
+    console.error(`Error: ${err && err.message ? err.message : err}`);
+  }
+  process.exitCode = 1;
+});

package/src/lib/color.mjs

@@ -0,0 +1,27 @@
+// Minimal raw-ANSI colorizer — no color libraries (zero-dependency rule).
+// Disabled automatically on non-TTY stdout or when NO_COLOR is set, per
+// https://no-color.org/.
+
+const CODES = {
+  bold: "1",
+  dim: "2",
+  green: "32",
+  cyan: "36",
+  yellow: "33",
+  red: "31",
+};
+
+/** Identity colorizer — used by the MCP server, which must never emit ANSI. */
+export const noColor = Object.fromEntries(
+  Object.keys(CODES).map((key) => [key, (text) => String(text)])
+);
+
+/**
+ * @returns {Record<keyof typeof CODES, (text: string) => string>}
+ */
+export function createColorizer() {
+  const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+  if (!enabled) return noColor;
+  const wrap = (code) => (text) => `\x1b[${code}m${text}\x1b[0m`;
+  return Object.fromEntries(Object.entries(CODES).map(([key, code]) => [key, wrap(code)]));
+}

package/src/lib/data.mjs

@@ -0,0 +1,137 @@
+// Shared data-fetching module for both the CLI and the MCP server.
+//
+// Fetches the live tokengratis.id provider directory at runtime (no bundled
+// copy shipped with this package). tokengratis.id is itself an AGGREGATOR,
+// not a verifier — this module just moves that data around, it never
+// invents or infers fields that aren't in the upstream JSON.
+//
+// Resolution order:
+//   1. Primary:  https://tokengratis.id/api/providers        (bare Provider[])
+//   2. Fallback: raw.githubusercontent.com .../data/providers.json
+//
+// Caching:
+//   - In-memory for the lifetime of the current process.
+//   - A short-TTL file cache in the OS temp dir so back-to-back CLI
+//     invocations (separate processes) don't re-fetch every time.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const PRIMARY_URL = "https://tokengratis.id/api/providers";
+export const FALLBACK_URL =
+  "https://raw.githubusercontent.com/raymondchins/tokengratis-id/main/data/providers.json";
+
+const FETCH_TIMEOUT_MS = 8000;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const CACHE_FILE = path.join(os.tmpdir(), "tokengratis-cli-cache.json");
+
+/** Thrown for any user-facing data problem (network, bad response, etc). */
+export class DataFetchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DataFetchError";
+  }
+}
+
+/** @type {{ providers: unknown[], fetchedAt: number, source: string } | null} */
+let memoryCache = null;
+
+async function fetchJson(url) {
+  let res;
+  try {
+    res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  } catch (err) {
+    if (err && err.name === "TimeoutError") {
+      throw new Error(`timeout setelah ${FETCH_TIMEOUT_MS}ms`);
+    }
+    throw new Error(err?.message || String(err));
+  }
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw new Error("respons bukan JSON valid");
+  }
+}
+
+function readFileCache() {
+  try {
+    const raw = fs.readFileSync(CACHE_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (
+      !parsed ||
+      typeof parsed.fetchedAt !== "number" ||
+      !Array.isArray(parsed.providers)
+    ) {
+      return null;
+    }
+    if (Date.now() - parsed.fetchedAt > CACHE_TTL_MS) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeFileCache(entry) {
+  try {
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), "utf8");
+  } catch {
+    // Best-effort — a stale/unwritable temp dir must never break the CLI/MCP server.
+  }
+}
+
+/**
+ * Get the current provider directory.
+ *
+ * @param {{ forceRefresh?: boolean }} [opts]
+ * @returns {Promise<{ providers: import("./types.mjs").Provider[], fetchedAt: number, source: string }>}
+ */
+export async function getProviders(opts = {}) {
+  const { forceRefresh = false } = opts;
+
+  if (memoryCache && !forceRefresh) return memoryCache;
+
+  if (!forceRefresh) {
+    const cached = readFileCache();
+    if (cached) {
+      memoryCache = cached;
+      return cached;
+    }
+  }
+
+  let providers;
+  let source = PRIMARY_URL;
+  let primaryErr;
+  try {
+    providers = await fetchJson(PRIMARY_URL);
+  } catch (err) {
+    primaryErr = err;
+    source = FALLBACK_URL;
+    try {
+      providers = await fetchJson(FALLBACK_URL);
+    } catch (fallbackErr) {
+      throw new DataFetchError(
+        "Gagal mengambil data provider tokengratis.id.\n" +
+          `  Primary  (${PRIMARY_URL}): ${primaryErr.message}\n` +
+          `  Fallback (${FALLBACK_URL}): ${fallbackErr.message}\n` +
+          "Cek koneksi internet kamu, atau coba lagi sebentar lagi."
+      );
+    }
+  }
+
+  if (!Array.isArray(providers)) {
+    throw new DataFetchError(
+      `Respons data provider dari ${source} tidak valid (bukan array JSON).`
+    );
+  }
+
+  const entry = { providers, fetchedAt: Date.now(), source };
+  memoryCache = entry;
+  writeFileCache(entry);
+  return entry;
+}

package/src/lib/filters.mjs

@@ -0,0 +1,85 @@
+// Filtering / searching helpers shared by the CLI and the MCP server.
+// Pure functions only — no I/O here.
+
+/**
+ * Parse a human-readable context-window string ("128K", "1M", "32000")
+ * into a plain token count. Returns null when it can't be parsed.
+ * @param {string | null | undefined} value
+ * @returns {number | null}
+ */
+export function parseContextTokens(value) {
+  if (!value) return null;
+  const match = String(value).trim().toUpperCase().match(/^([\d.]+)\s*([KM])?$/);
+  if (!match) return null;
+  const num = parseFloat(match[1]);
+  if (Number.isNaN(num)) return null;
+  const mult = match[2] === "M" ? 1_000_000 : match[2] === "K" ? 1_000 : 1;
+  return num * mult;
+}
+
+/**
+ * @param {import("./types.mjs").Provider[]} providers
+ * @param {string | undefined} modality
+ */
+export function filterByModality(providers, modality) {
+  if (!modality) return providers;
+  const target = modality.trim().toLowerCase();
+  return providers.filter((p) =>
+    (p.modalities || []).some((m) => String(m).toLowerCase() === target)
+  );
+}
+
+/**
+ * @param {import("./types.mjs").Provider[]} providers
+ * @param {string | undefined} minContext
+ */
+export function filterByMinContext(providers, minContext) {
+  const threshold = parseContextTokens(minContext);
+  if (threshold == null) return providers;
+  return providers.filter((p) => {
+    const value = parseContextTokens(p.maxContext);
+    return value != null && value >= threshold;
+  });
+}
+
+/**
+ * Match provider names/slugs and model names/ids against a query substring.
+ * @param {import("./types.mjs").Provider[]} providers
+ * @param {string} query
+ * @returns {{ provider: import("./types.mjs").Provider, matchedModels: import("./types.mjs").Model[], providerMatch: boolean }[]}
+ */
+export function searchProviders(providers, query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const results = [];
+  for (const p of providers) {
+    const providerMatch =
+      (p.name || "").toLowerCase().includes(q) || (p.slug || "").toLowerCase().includes(q);
+    const matchedModels = (p.models || []).filter(
+      (m) =>
+        (m.name || "").toLowerCase().includes(q) || (m.id || "").toLowerCase().includes(q)
+    );
+    if (providerMatch || matchedModels.length > 0) {
+      results.push({ provider: p, matchedModels, providerMatch });
+    }
+  }
+  return results;
+}
+
+/**
+ * Flatten providers -> models, optionally scoped to one provider slug.
+ * @param {import("./types.mjs").Provider[]} providers
+ * @param {string | undefined} providerSlug
+ */
+export function listModels(providers, providerSlug) {
+  const scoped = providerSlug
+    ? providers.filter((p) => p.slug === providerSlug)
+    : providers;
+  const rows = [];
+  for (const p of scoped) {
+    for (const m of p.models || []) {
+      rows.push({ provider: p.slug, providerName: p.name, ...m });
+    }
+  }
+  return rows;
+}

package/src/lib/render.mjs

@@ -0,0 +1,109 @@
+// Human-readable text rendering, shared by the CLI (with optional ANSI
+// color) and the MCP server (always plain — the LLM reads this text).
+//
+// The project's #1 rule is aggregator-not-verifier: renderers here always
+// carry provenance (sources[] + syncedAt) and NEVER emit the word
+// "Verified" / "Terverifikasi".
+
+import { noColor } from "./color.mjs";
+
+/**
+ * @param {import("./types.mjs").Provider[]} providers
+ * @param {{ color?: typeof noColor }} [opts]
+ */
+export function formatProviderListText(providers, opts = {}) {
+  const color = opts.color || noColor;
+  if (providers.length === 0) return "Tidak ada provider yang cocok dengan filter ini.";
+  return providers
+    .map((p) => {
+      const modalities = (p.modalities || []).join(", ") || "-";
+      const ctx = p.maxContext || "-";
+      return `${color.bold(p.name)} (${color.dim(p.slug)})  models=${p.modelCount}  context=${ctx}  modalities=${modalities}`;
+    })
+    .join("\n");
+}
+
+/**
+ * @param {import("./types.mjs").Provider} p
+ * @param {{ color?: typeof noColor }} [opts]
+ */
+export function formatProviderText(p, opts = {}) {
+  const color = opts.color || noColor;
+  const lines = [];
+  lines.push(`${color.bold(p.name)} (${p.slug})`);
+  if (p.category) lines.push(`Kategori: ${p.category}`);
+  if (p.country) lines.push(`Negara (HQ): ${p.flag ? p.flag + " " : ""}${p.country}`);
+  if (p.url) lines.push(`Halaman API key: ${p.url}`);
+  if (p.baseUrl) lines.push(`Base URL: ${p.baseUrl}`);
+  if (p.freeLimit) lines.push(`Free limit: ${p.freeLimit}`);
+  if (p.description) lines.push(`Deskripsi (apa adanya dari sumber): ${p.description}`);
+  if (p.moreModels) lines.push(`Catatan: ${p.moreModels}`);
+  lines.push(`Modalitas: ${(p.modalities || []).join(", ") || "-"}`);
+  lines.push(`Max context: ${p.maxContext || "-"}`);
+
+  lines.push("");
+  const models = p.models || [];
+  lines.push(color.bold(`Models (${models.length}):`));
+  if (models.length === 0) {
+    lines.push("  (tidak ada model terstruktur dari sumber)");
+  }
+  for (const m of models) {
+    const parts = [m.name || m.id];
+    if (m.context) parts.push(`context=${m.context}`);
+    if (m.maxOutput) parts.push(`maxOutput=${m.maxOutput}`);
+    if (m.modality) parts.push(`modality=${m.modality}`);
+    if (m.rateLimit) parts.push(`rateLimit=${m.rateLimit}`);
+    lines.push(`  - ${parts.join("  ")}`);
+  }
+
+  lines.push("");
+  lines.push(color.bold("Provenance (aggregator, bukan verifier):"));
+  for (const s of p.sources || []) {
+    lines.push(`  - ${s.name}: ${s.url} (synced ${s.syncedAt})`);
+  }
+  lines.push(`Synced: ${p.syncedAt}`);
+  if (p.sourceUpdatedAt) lines.push(`Source last updated: ${p.sourceUpdatedAt}`);
+
+  return lines.join("\n");
+}
+
+/**
+ * @param {ReturnType<import("./filters.mjs").listModels>} rows
+ * @param {{ color?: typeof noColor }} [opts]
+ */
+export function formatModelListText(rows, opts = {}) {
+  const color = opts.color || noColor;
+  if (rows.length === 0) return "Tidak ada model.";
+  return rows
+    .map((m) => {
+      const parts = [`${color.bold(m.providerName)}/${m.name || m.id}`];
+      if (m.context) parts.push(`context=${m.context}`);
+      if (m.modality) parts.push(`modality=${m.modality}`);
+      if (m.rateLimit) parts.push(`rateLimit=${m.rateLimit}`);
+      return parts.join("  ");
+    })
+    .join("\n");
+}
+
+/**
+ * @param {ReturnType<import("./filters.mjs").searchProviders>} results
+ * @param {string} query
+ * @param {{ color?: typeof noColor }} [opts]
+ */
+export function formatSearchResultsText(results, query, opts = {}) {
+  const color = opts.color || noColor;
+  if (results.length === 0) return `Tidak ada hasil untuk "${query}".`;
+  const lines = [`Hasil pencarian untuk "${query}" — ${results.length} provider cocok:`, ""];
+  for (const r of results) {
+    const tag = r.matchedModels.length === 0 && r.providerMatch ? " (cocok nama provider)" : "";
+    lines.push(`${color.bold(r.provider.name)} (${r.provider.slug})${tag}`);
+    const shown = r.matchedModels.slice(0, 10);
+    for (const m of shown) {
+      lines.push(`  - ${m.name || m.id}`);
+    }
+    if (r.matchedModels.length > shown.length) {
+      lines.push(`  ... +${r.matchedModels.length - shown.length} model lain`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/lib/types.mjs

@@ -0,0 +1,52 @@
+// JSDoc-only type definitions mirroring tokengratis-id's `lib/types.ts`
+// (the canonical schema). No runtime code — this file exists purely so
+// editors can resolve the `import("./types.mjs").Provider` JSDoc references
+// used elsewhere in this package. Kept in sync loosely; the live JSON from
+// the API is always the source of truth, this package never validates or
+// invents fields beyond what upstream sends.
+
+/**
+ * @typedef {"provider_api" | "inference_provider"} ProviderCategory
+ */
+
+/**
+ * @typedef {Object} Model
+ * @property {string} id
+ * @property {string} name
+ * @property {string | null} context
+ * @property {string | null} maxOutput
+ * @property {string | null} modality
+ * @property {string | null} rateLimit
+ */
+
+/**
+ * @typedef {Object} SourceRef
+ * @property {string} name
+ * @property {string} url
+ * @property {string} syncedAt
+ */
+
+/**
+ * @typedef {Object} Provider
+ * @property {string} slug
+ * @property {string} name
+ * @property {ProviderCategory | null} category
+ * @property {string | null} country
+ * @property {string | null} flag
+ * @property {string | null} domain
+ * @property {string | null} logo
+ * @property {string | null} url
+ * @property {string | null} baseUrl
+ * @property {string} [description]
+ * @property {string[]} modalities
+ * @property {number} modelCount
+ * @property {string | null} maxContext
+ * @property {string | null} freeLimit
+ * @property {string | null} moreModels
+ * @property {Model[]} models
+ * @property {SourceRef[]} sources
+ * @property {string} syncedAt
+ * @property {string | null} sourceUpdatedAt
+ */
+
+export {};

package/src/mcp-server.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+// tokengratis-mcp — Model Context Protocol server for the tokengratis.id
+// free-tier LLM API directory, implemented by hand over stdio
+// (newline-delimited JSON-RPC 2.0). Zero dependencies, no SDK.
+//
+// HARD RULE: nothing but JSON-RPC may ever touch stdout. All logging /
+// diagnostics go to stderr, always.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import { getProviders, DataFetchError } from "./lib/data.mjs";
+import { filterByModality, filterByMinContext, searchProviders, listModels } from "./lib/filters.mjs";
+import {
+  formatProviderListText,
+  formatProviderText,
+  formatModelListText,
+  formatSearchResultsText,
+} from "./lib/render.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+
+const SERVER_NAME = "tokengratis-mcp";
+const SERVER_VERSION = pkg.version;
+const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+
+const TOOLS = [
+  {
+    name: "list_providers",
+    description:
+      "List free-tier LLM API providers from the tokengratis.id directory (Indonesia-focused, community-aggregated — this is an aggregator, not an authority that checks each claim). Optional filters by modality and minimum context window. Each result carries model counts; use get_provider for full detail + provenance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        modality: {
+          type: "string",
+          description:
+            "Filter by capability, e.g. text, vision, image, audio, video, code, embeddings, reranking.",
+        },
+        min_context: {
+          type: "string",
+          description: "Minimum context window, e.g. '128K' or '1M'.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_provider",
+    description:
+      "Get full detail for one tokengratis.id provider by slug: base URL, free-tier limit description, its models, and provenance (which source(s) contributed the data and when each was synced). This is an aggregator, not a verifier.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: {
+          type: "string",
+          description: "Provider slug, e.g. 'openrouter'. Use list_providers to discover slugs.",
+        },
+      },
+      required: ["slug"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "search_models",
+    description:
+      "Search tokengratis.id providers and models by substring match against provider name/slug and model name/id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search text, e.g. 'llama' or 'groq'." },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_models",
+    description: "Flat list of models across all tokengratis.id providers, optionally scoped to one provider slug.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", description: "Optional provider slug to scope results to." },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+class ToolInputError extends Error {}
+class ToolNotFoundError extends Error {}
+
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+async function callTool(name, rawArgs) {
+  const args = rawArgs && typeof rawArgs === "object" ? rawArgs : {};
+  const { providers } = await getProviders();
+
+  switch (name) {
+    case "list_providers": {
+      let list = providers;
+      list = filterByModality(list, args.modality);
+      list = filterByMinContext(list, args.min_context);
+      return textResult(formatProviderListText(list));
+    }
+    case "get_provider": {
+      if (!args.slug || typeof args.slug !== "string") {
+        throw new ToolInputError("Parameter 'slug' wajib diisi (string).");
+      }
+      const p = providers.find((x) => x.slug === args.slug);
+      if (!p) {
+        throw new ToolInputError(`Provider dengan slug "${args.slug}" tidak ditemukan.`);
+      }
+      return textResult(formatProviderText(p));
+    }
+    case "search_models": {
+      if (!args.query || typeof args.query !== "string") {
+        throw new ToolInputError("Parameter 'query' wajib diisi (string).");
+      }
+      const results = searchProviders(providers, args.query);
+      return textResult(formatSearchResultsText(results, args.query));
+    }
+    case "list_models": {
+      const rows = listModels(providers, typeof args.provider === "string" ? args.provider : undefined);
+      return textResult(formatModelListText(rows));
+    }
+    default:
+      throw new ToolNotFoundError(`Unknown tool: ${name}`);
+  }
+}
+
+// ---- JSON-RPC plumbing -----------------------------------------------
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function sendError(id, code, message, data) {
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  send({ jsonrpc: "2.0", id, error });
+}
+
+/** @param {any} msg */
+async function handleMessage(msg) {
+  if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
+    // Not a valid single JSON-RPC object. We have no id to reply against
+    // meaningfully, but report a parse/invalid-request error anyway.
+    sendError(null, -32700, "Parse error: expected a JSON object");
+    return;
+  }
+
+  const hasId = Object.prototype.hasOwnProperty.call(msg, "id");
+  const { method } = msg;
+
+  // Notifications (no "id") never get a response, per JSON-RPC 2.0 / MCP.
+  if (!hasId) {
+    if (method !== "notifications/initialized") {
+      console.error(`[${SERVER_NAME}] notification: ${method}`);
+    }
+    return;
+  }
+
+  try {
+    switch (method) {
+      case "initialize": {
+        const requested = msg.params && msg.params.protocolVersion;
+        sendResult(msg.id, {
+          protocolVersion: typeof requested === "string" ? requested : DEFAULT_PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        });
+        return;
+      }
+      case "ping": {
+        sendResult(msg.id, {});
+        return;
+      }
+      case "tools/list": {
+        sendResult(msg.id, { tools: TOOLS });
+        return;
+      }
+      case "tools/call": {
+        const params = msg.params || {};
+        try {
+          const result = await callTool(params.name, params.arguments);
+          sendResult(msg.id, result);
+        } catch (err) {
+          if (err instanceof ToolNotFoundError) {
+            sendError(msg.id, -32601, err.message);
+          } else if (err instanceof ToolInputError || err instanceof DataFetchError) {
+            // Tool-level failure: valid JSON-RPC response, but flagged as an
+            // error result so the model sees it as text, not a protocol error.
+            sendResult(msg.id, { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true });
+          } else {
+            sendError(msg.id, -32603, err && err.message ? err.message : String(err));
+          }
+        }
+        return;
+      }
+      default:
+        sendError(msg.id, -32601, `Method not found: ${method}`);
+    }
+  } catch (err) {
+    sendError(msg.id, -32603, err && err.message ? err.message : String(err));
+  }
+}
+
+function main() {
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+
+  // Tool calls are async (they fetch over the network). If stdin closes
+  // while one is still in flight — e.g. a client that writes its requests
+  // and immediately closes the pipe — we must NOT exit until every
+  // in-flight response has actually been written to stdout, or replies
+  // silently vanish.
+  let pending = 0;
+  let closing = false;
+  const maybeExit = () => {
+    if (closing && pending === 0) process.exit(0);
+  };
+
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      sendError(null, -32700, "Parse error: invalid JSON");
+      return;
+    }
+
+    // Be tolerant of JSON-RPC batch arrays even though MCP stdio normally
+    // sends one message per line.
+    const messages = Array.isArray(msg) ? msg : [msg];
+    for (const m of messages) {
+      pending++;
+      handleMessage(m)
+        .catch((err) => {
+          console.error(`[${SERVER_NAME}] unhandled error:`, err);
+        })
+        .finally(() => {
+          pending--;
+          maybeExit();
+        });
+    }
+  });
+
+  rl.on("close", () => {
+    closing = true;
+    maybeExit();
+  });
+
+  console.error(`[${SERVER_NAME}] v${SERVER_VERSION} ready (stdio, JSON-RPC 2.0)`);
+}
+
+main();