@mafdet/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mafdet AI
+
+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,94 @@
+# @mafdet/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that brings
+**read-only Mafdet AI account tools** into Claude Code, Claude Desktop, Cursor,
+Codex CLI, OpenCode, and any other MCP client.
+
+It does **not** run model inference — you keep calling Mafdet AI models through
+each tool's normal OpenAI-compatible endpoint. This server only exposes
+read-only account and documentation helpers.
+
+## Tools
+
+| Tool | Needs a key | What it does |
+| --- | --- | --- |
+| `list_models` | no | List Mafdet AI models with provider, tier, and per-1M-token pricing |
+| `search_docs` | no | Search the Mafdet AI documentation (titles, URLs, summaries) |
+| `get_balance` | yes | Your organization's wallet: balance, bonus, frozen, available |
+| `get_usage_summary` | yes | Requests, tokens, and charge over the last N days (1–90) |
+| `get_subscription` | yes | Current plan, status, period, and Playground credit |
+
+The account tools are **read-only** — there is no key management, recharge,
+refund, subscription change, or any write operation.
+
+## Configuration
+
+Set these environment variables (all optional):
+
+- `MAFDET_API_KEY` — a Mafdet AI key **with the `account:read` scope**. Only the
+  account tools need it; `list_models` and `search_docs` work without a key.
+  Create a key with the scope in the Console (API Keys → "Allow the local MCP
+  server to read this account"). Prefer your client's secret/env configuration
+  over putting the key on a command line.
+- `MAFDET_BASE_URL` — defaults to `https://backend.mafdet.ai`. Only change it for
+  local/staging testing; it must be an `https://` URL.
+- `MAFDET_DOCS_URL` — defaults to `https://docs.mafdet.ai`.
+
+## Client setup
+
+### Claude Code
+
+```sh
+claude mcp add mafdet --env MAFDET_API_KEY=sk-mafdet-live-... -- npx -y @mafdet/mcp
+```
+
+### Claude Desktop / Cursor / other MCP clients
+
+Add to the client's MCP config (`claude_desktop_config.json`, Cursor MCP
+settings, etc.):
+
+```json
+{
+  "mcpServers": {
+    "mafdet": {
+      "command": "npx",
+      "args": ["-y", "@mafdet/mcp"],
+      "env": { "MAFDET_API_KEY": "sk-mafdet-live-..." }
+    }
+  }
+}
+```
+
+### Codex CLI (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.mafdet]
+command = "npx"
+args = ["-y", "@mafdet/mcp"]
+env = { MAFDET_API_KEY = "sk-mafdet-live-..." }
+```
+
+### OpenCode (`opencode.json`)
+
+```json
+{
+  "mcp": {
+    "mafdet": {
+      "type": "local",
+      "command": ["npx", "-y", "@mafdet/mcp"],
+      "environment": { "MAFDET_API_KEY": "sk-mafdet-live-..." }
+    }
+  }
+}
+```
+
+Omit `MAFDET_API_KEY` to use only the public tools (`list_models`,
+`search_docs`).
+
+## Notes
+
+- Pin a major version (`@mafdet/mcp@0`) in automated setups to avoid surprise
+  upgrades.
+- The server writes only JSON-RPC to stdout; diagnostics go to stderr and never
+  include your key.
+- Requires Node.js 20+.

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+export type MafdetErrorKind = "unauthorized" | "forbidden" | "rate_limited" | "unavailable" | "network" | "bad_response";
+export declare class MafdetClientError extends Error {
+    readonly kind: MafdetErrorKind;
+    constructor(kind: MafdetErrorKind, message: string);
+}
+interface GetJsonOptions {
+    baseUrl: string;
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    authKey?: string;
+    timeoutMs?: number;
+}
+export declare function getJson(options: GetJsonOptions): Promise<unknown>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,WAAW,GACX,cAAc,GACd,aAAa,GACb,SAAS,GACT,cAAc,CAAC;AAEnB,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,IAAI,EAAE,eAAe;gBAArB,IAAI,EAAE,eAAe,EACrC,OAAO,EAAE,MAAM;CAKlB;AAED,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAEpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAkDvE"}

package/dist/client.js

@@ -0,0 +1,106 @@
+import { redact } from "./logger.js";
+// MCP-002B: the single HTTP client for every Mafdet call. It enforces a total
+// timeout, a response-body size cap, and JSON validation; attaches the Bearer
+// key ONLY on account requests; and maps every failure to a stable, actionable
+// message that never echoes the upstream body, headers, or the key.
+const DEFAULT_TIMEOUT_MS = 12_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+export class MafdetClientError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "MafdetClientError";
+    }
+}
+export async function getJson(options) {
+    const url = buildUrl(options.baseUrl, options.path, options.query);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        const headers = { Accept: "application/json" };
+        if (options.authKey) {
+            headers.Authorization = `Bearer ${options.authKey}`;
+        }
+        response = await fetch(url, {
+            method: "GET",
+            headers,
+            signal: controller.signal,
+            redirect: "error",
+        });
+    }
+    catch (error) {
+        throw new MafdetClientError("network", `could not reach Mafdet AI (${describeNetworkError(error)})`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw mapStatus(response.status);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/json")) {
+        throw new MafdetClientError("bad_response", "Mafdet AI returned an unexpected (non-JSON) response");
+    }
+    const text = await readBounded(response);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new MafdetClientError("bad_response", "Mafdet AI returned malformed JSON");
+    }
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(path.startsWith("/") ? path : `/${path}`, baseUrl);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+function mapStatus(status) {
+    if (status === 401) {
+        return new MafdetClientError("unauthorized", "the Mafdet AI API key is missing, invalid, expired, or revoked");
+    }
+    if (status === 403) {
+        return new MafdetClientError("forbidden", "this API key lacks the account:read scope (create a key with it enabled)");
+    }
+    if (status === 429) {
+        return new MafdetClientError("rate_limited", "rate limited by Mafdet AI; wait a moment and try again");
+    }
+    return new MafdetClientError("unavailable", `Mafdet AI is temporarily unavailable (HTTP ${status})`);
+}
+// Read the response body but never buffer more than the cap.
+async function readBounded(response) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return "";
+    }
+    const decoder = new TextDecoder();
+    let total = 0;
+    let out = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > MAX_RESPONSE_BYTES) {
+            await reader.cancel();
+            throw new MafdetClientError("bad_response", "Mafdet AI response exceeded the size limit");
+        }
+        out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+    return out;
+}
+function describeNetworkError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+        return "timed out";
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return redact(message);
+}

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export interface McpConfig {
+    apiKey: string | undefined;
+    baseUrl: string;
+    docsUrl: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AA4BD,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAO1E"}

package/dist/config.js

@@ -0,0 +1,36 @@
+// MCP-002A: runtime configuration from the environment. MAFDET_API_KEY is
+// optional — only the account tools need it; list_models and search_docs work
+// without a key. Base URLs default to production and may be overridden for
+// local/staging validation. We never print any of these values.
+const DEFAULT_BASE_URL = "https://backend.mafdet.ai";
+const DEFAULT_DOCS_URL = "https://docs.mafdet.ai";
+// Only https is accepted for a remote host, so a key is never sent in the clear.
+// localhost/127.0.0.1 over http is allowed for local development only.
+function sanitizeBaseUrl(raw, fallback) {
+    const value = raw?.trim();
+    if (!value) {
+        return fallback;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`invalid URL in configuration: ${value}`);
+    }
+    const isLocalHttp = url.protocol === "http:" &&
+        (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+    if (url.protocol !== "https:" && !isLocalHttp) {
+        throw new Error("base URL must be https (http allowed only for localhost)");
+    }
+    // Drop any trailing slash so path joins are predictable.
+    return url.origin;
+}
+export function loadConfig(env = process.env) {
+    const apiKey = env.MAFDET_API_KEY?.trim();
+    return {
+        apiKey: apiKey && apiKey.length > 0 ? apiKey : undefined,
+        baseUrl: sanitizeBaseUrl(env.MAFDET_BASE_URL, DEFAULT_BASE_URL),
+        docsUrl: sanitizeBaseUrl(env.MAFDET_DOCS_URL, DEFAULT_DOCS_URL),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function buildServer(config?: import("./config.js").McpConfig): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgBpE,wBAAgB,WAAW,CAAC,MAAM,kCAAe,GAAG,SAAS,CAmE5D"}

package/dist/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { logError } from "./logger.js";
+import { getBalance, getSubscription, getUsageSummary, listModels, searchDocsTool, } from "./tools.js";
+// MCP-002A: the stdio entry point. stdout carries only JSON-RPC (the SDK owns
+// it); everything diagnostic goes to stderr via logError. The five tools are
+// read-only; account tools need MAFDET_API_KEY, the two public tools do not.
+export function buildServer(config = loadConfig()) {
+    const server = new McpServer({ name: "mafdet-mcp", version: "0.1.0" });
+    server.registerTool("list_models", {
+        title: "List Mafdet AI models",
+        description: "List the models available on Mafdet AI with provider, tier, and per-1M-token pricing. No API key required.",
+        inputSchema: {
+            provider: z.string().min(1).max(40).optional(),
+            tier: z.string().min(1).max(40).optional(),
+        },
+    }, (args) => listModels(config, args));
+    server.registerTool("get_balance", {
+        title: "Get account balance",
+        description: "Read the current organization's wallet balance, bonus, frozen, and available amounts. Requires a MAFDET_API_KEY with the account:read scope.",
+        inputSchema: {},
+    }, () => getBalance(config));
+    server.registerTool("get_usage_summary", {
+        title: "Get usage summary",
+        description: "Summarize the organization's API usage over a recent window (requests, tokens, charge). Requires account:read.",
+        inputSchema: {
+            days: z.number().int().min(1).max(90).optional(),
+        },
+    }, (args) => getUsageSummary(config, args));
+    server.registerTool("get_subscription", {
+        title: "Get subscription",
+        description: "Read the organization's current plan, status, period, and Playground credit summary. Requires account:read.",
+        inputSchema: {},
+    }, () => getSubscription(config));
+    server.registerTool("search_docs", {
+        title: "Search Mafdet AI docs",
+        description: "Search the Mafdet AI documentation and return titles, URLs, and summaries. No API key required.",
+        inputSchema: {
+            query: z.string().min(1).max(100),
+            limit: z.number().int().min(1).max(10).optional(),
+        },
+    }, (args) => searchDocsTool(config, args));
+    return server;
+}
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = () => {
+        void server.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+// Only run when invoked as the binary, not when imported by tests.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((error) => {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+export declare function redact(message: string): string;
+export declare function logError(message: string): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAOA,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI9C;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9C"}

package/dist/logger.js

@@ -0,0 +1,13 @@
+// MCP-002A: stdout is the JSON-RPC channel for a stdio MCP server, so ALL
+// diagnostics go to stderr. Never log the API key or an Authorization header —
+// redact anything that looks like one before writing.
+const KEY_LIKE = /sk-mafdet-[a-z-]*[A-Za-z0-9_-]+/g;
+const BEARER = /Bearer\s+[A-Za-z0-9._-]+/gi;
+export function redact(message) {
+    return message
+        .replace(BEARER, "Bearer [redacted]")
+        .replace(KEY_LIKE, "[redacted-key]");
+}
+export function logError(message) {
+    process.stderr.write(`[mafdet-mcp] ${redact(message)}\n`);
+}

package/dist/search-docs.d.ts

@@ -0,0 +1,13 @@
+export interface DocHit {
+    title: string;
+    url: string;
+    summary: string;
+}
+export declare function searchDocs(input: {
+    docsUrl: string;
+    query: string;
+    limit: number;
+    docsBaseForUrl?: string;
+}): Promise<DocHit[]>;
+export declare function resetDocsCache(): void;
+//# sourceMappingURL=search-docs.d.ts.map

package/dist/search-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-docs.d.ts","sourceRoot":"","sources":["../src/search-docs.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAuCD,wBAAsB,UAAU,CAAC,KAAK,EAAE;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0BpB;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/search-docs.js

@@ -0,0 +1,52 @@
+import { getJson, MafdetClientError } from "./client.js";
+let cache;
+async function loadIndex(docsUrl) {
+    if (cache && cache.docsUrl === docsUrl) {
+        return cache.docs;
+    }
+    const body = await getJson({ baseUrl: docsUrl, path: "/search-index.json" });
+    if (!body ||
+        typeof body !== "object" ||
+        !Array.isArray(body.docs)) {
+        throw new MafdetClientError("bad_response", "the docs search index is malformed");
+    }
+    const docs = body.docs.filter((doc) => doc &&
+        typeof doc.title === "string" &&
+        typeof doc.url === "string" &&
+        typeof doc.text === "string");
+    cache = { docsUrl, docs };
+    return docs;
+}
+export async function searchDocs(input) {
+    const docs = await loadIndex(input.docsUrl);
+    const needle = input.query.trim().toLowerCase();
+    if (!needle) {
+        return [];
+    }
+    const base = input.docsBaseForUrl ?? input.docsUrl;
+    const scored = [];
+    for (const doc of docs) {
+        const title = doc.title.toLowerCase();
+        const text = doc.text.toLowerCase();
+        // Title matches rank above body matches; skip non-matches entirely.
+        let score = 0;
+        if (title.includes(needle))
+            score += 2;
+        if (text.includes(needle))
+            score += 1;
+        if (score > 0) {
+            scored.push({ doc, score });
+        }
+    }
+    // Stable ordering: score desc, then id asc (docs are pre-sorted by id).
+    scored.sort((a, b) => b.score - a.score || a.doc.id.localeCompare(b.doc.id));
+    return scored.slice(0, input.limit).map(({ doc }) => ({
+        title: doc.title,
+        url: new URL(doc.url, base).toString(),
+        summary: doc.summary,
+    }));
+}
+// Test seam: reset the in-process cache.
+export function resetDocsCache() {
+    cache = undefined;
+}

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+import type { McpConfig } from "./config.js";
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare function listModels(config: McpConfig, args?: {
+    provider?: string;
+    tier?: string;
+}): Promise<ToolResult>;
+export declare function getBalance(config: McpConfig): Promise<ToolResult>;
+export declare function getUsageSummary(config: McpConfig, args?: {
+    days?: number;
+}): Promise<ToolResult>;
+export declare function getSubscription(config: McpConfig): Promise<ToolResult>;
+export declare function searchDocsTool(config: McpConfig, args: {
+    query: string;
+    limit?: number;
+}): Promise<ToolResult>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAW7C,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAkCD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,UAAU,CAAC,CAmCrB;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBvE;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3B,OAAO,CAAC,UAAU,CAAC,CAmBrB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CA+B5E;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,UAAU,CAAC,CAkBrB"}

package/dist/tools.js

@@ -0,0 +1,145 @@
+import { getJson, MafdetClientError } from "./client.js";
+import { searchDocs } from "./search-docs.js";
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function fail(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+// Turn any thrown client error into a readable tool error (never leaks bodies).
+function fromError(error) {
+    if (error instanceof MafdetClientError) {
+        return fail(error.message);
+    }
+    return fail("unexpected error talking to Mafdet AI");
+}
+function requireKey(config) {
+    if (!config.apiKey) {
+        return fail("No MAFDET_API_KEY is set. Set it (a Mafdet AI key with the account:read scope) to use this tool. list_models and search_docs work without a key.");
+    }
+    return config.apiKey;
+}
+// micro-USD (integer string) -> "$0.28" style; keeps the raw value alongside.
+function usd(microString) {
+    const micro = Number(microString ?? "0");
+    if (!Number.isFinite(micro))
+        return "$0.00";
+    return `$${(micro / 1_000_000).toFixed(micro % 10_000 === 0 ? 2 : 4)}`;
+}
+export async function listModels(config, args = {}) {
+    try {
+        const body = await getJson({ baseUrl: config.baseUrl, path: "/models" });
+        const rows = Array.isArray(body.data)
+            ? body.data
+            : [];
+        const provider = args.provider?.toLowerCase();
+        const tier = args.tier?.toLowerCase();
+        const models = rows
+            .filter((m) => !provider || String(m.provider).toLowerCase() === provider)
+            .filter((m) => !tier || String(m.accessTier).toLowerCase() === tier)
+            .map((m) => ({
+            model_id: m.modelId,
+            display_name: m.displayName,
+            provider: m.provider,
+            tier: m.accessTier,
+            input_per_1m_micro_usd: String(m.inputPricePer1mMicroUsd ?? "0"),
+            output_per_1m_micro_usd: String(m.outputPricePer1mMicroUsd ?? "0"),
+            context_length: m.contextLength,
+            trial: Boolean(m.isTrialEnabled),
+            deprecated: Boolean(m.deprecated),
+        }));
+        if (models.length === 0) {
+            return ok("No models matched the filter.");
+        }
+        const lines = models.map((m) => `- ${m.model_id} (${m.provider}, ${m.tier})` +
+            `${m.trial ? " [trial]" : ""}${m.deprecated ? " [deprecated]" : ""}` +
+            ` — in ${usd(m.input_per_1m_micro_usd)}/1M, out ${usd(m.output_per_1m_micro_usd)}/1M, ctx ${m.context_length}`);
+        return ok(`Mafdet AI models (${models.length}):\n${lines.join("\n")}`);
+    }
+    catch (error) {
+        return fromError(error);
+    }
+}
+export async function getBalance(config) {
+    const key = requireKey(config);
+    if (typeof key !== "string")
+        return key;
+    try {
+        const w = (await getJson({
+            baseUrl: config.baseUrl,
+            path: "/keyinfo/wallet",
+            authKey: key,
+        }));
+        const text = `Available: ${usd(w.available_micro_usd)} ` +
+            `(balance ${usd(w.balance_micro_usd)} + bonus ${usd(w.bonus_micro_usd)} ` +
+            `− frozen ${usd(w.frozen_micro_usd)}), anchored in ${String(w.currency_anchor).toUpperCase()}.`;
+        return ok(text);
+    }
+    catch (error) {
+        return fromError(error);
+    }
+}
+export async function getUsageSummary(config, args = {}) {
+    const key = requireKey(config);
+    if (typeof key !== "string")
+        return key;
+    const days = args.days ?? 7;
+    try {
+        const u = (await getJson({
+            baseUrl: config.baseUrl,
+            path: "/keyinfo/usage-summary",
+            query: { days },
+            authKey: key,
+        }));
+        const text = `Last ${u.days} day(s): ${u.count} request(s), ` +
+            `${u.input_tokens} in / ${u.output_tokens} out (${u.total_tokens} total tokens), ` +
+            `charge ${usd(String(u.charge_micro_usd))}.`;
+        return ok(text);
+    }
+    catch (error) {
+        return fromError(error);
+    }
+}
+export async function getSubscription(config) {
+    const key = requireKey(config);
+    if (typeof key !== "string")
+        return key;
+    try {
+        const s = (await getJson({
+            baseUrl: config.baseUrl,
+            path: "/keyinfo/subscription",
+            authKey: key,
+        }));
+        const planLine = s.plan_name
+            ? `Plan: ${s.plan_name} (${s.status ?? "unknown"})`
+            : "No active subscription (default entitlement).";
+        const pg = s.playground
+            ? ` Playground credit: ${usd(s.playground.remaining_micro_usd)} left of ${usd(s.playground.allowance_micro_usd)}.`
+            : "";
+        const period = s.current_period_end
+            ? ` Period ends ${s.current_period_end}.`
+            : "";
+        return ok(`${planLine}.${pg}${period}`);
+    }
+    catch (error) {
+        return fromError(error);
+    }
+}
+export async function searchDocsTool(config, args) {
+    const limit = Math.min(Math.max(args.limit ?? 5, 1), 10);
+    try {
+        const hits = await searchDocs({
+            docsUrl: config.docsUrl,
+            query: args.query,
+            limit,
+        });
+        if (hits.length === 0) {
+            return ok(`No documentation matched "${args.query}".`);
+        }
+        const lines = hits.map((h) => `- ${h.title}\n  ${h.url}\n  ${h.summary}`);
+        return ok(`Documentation matches for "${args.query}" (${hits.length}):\n${lines.join("\n")}`);
+    }
+    catch (error) {
+        return fromError(error);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mafdet/mcp",
+  "version": "0.1.0",
+  "description": "Mafdet AI MCP server — read-only account tools (models, balance, usage, subscription, docs) for Claude Code, Cursor, Codex, OpenCode, and Claude Desktop.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mafdet AI",
+  "homepage": "https://www.mafdet.ai",
+  "bugs": {
+    "email": "support@mafdet.ai"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mafdet",
+    "ai",
+    "llm",
+    "claude",
+    "cursor",
+    "codex",
+    "opencode"
+  ],
+  "bin": {
+    "mafdet-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "mcpName": "ai.mafdet/mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "prettier --check \"src/**/*.ts\" \"test/**/*.mjs\" package.json tsconfig.json",
+    "test": "pnpm run build && node --test \"test/**/*.test.mjs\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}