@scriptmasterlabs/scriptdocs-mcp-server - npm Package Compare versions

Comparing version 0.2.0 to 0.3.0

dist/services/access.d.ts

+/**
+ * FOUNDER ALWAYS-FREE GUARANTEE
+ * =============================
+ * ScriptMaster Labs (the project owner) always has full, unmetered,
+ * un-rate-limited, free access to every tool this server exposes —
+ * regardless of whatever paid tiers, rate limits, or x402 payment
+ * gates get added later.
+ *
+ * This is enforced by comparing a caller-supplied key against the
+ * `SCRIPTDOCS_OWNER_KEY` environment variable — never a hardcoded
+ * value in source (this repo is public/MIT-licensed; hardcoding a
+ * bypass secret here would hand it to everyone, not just the owner).
+ *
+ * RULE FOR FUTURE CODE: any billing, rate-limiting, or paywall logic
+ * added to this server MUST call `isOwnerRequest()` first and skip
+ * all limits/charges/metering when it returns true. This function
+ * existing is the guarantee — wire it in before shipping any gate.
+ */
+export declare function isOwnerRequest(providedKey: string | undefined | null): boolean;

dist/services/access.js

+import { timingSafeEqual } from "node:crypto";
+import { OWNER_KEY_ENV_VAR } from "../constants.js";
+/**
+ * FOUNDER ALWAYS-FREE GUARANTEE
+ * =============================
+ * ScriptMaster Labs (the project owner) always has full, unmetered,
+ * un-rate-limited, free access to every tool this server exposes —
+ * regardless of whatever paid tiers, rate limits, or x402 payment
+ * gates get added later.
+ *
+ * This is enforced by comparing a caller-supplied key against the
+ * `SCRIPTDOCS_OWNER_KEY` environment variable — never a hardcoded
+ * value in source (this repo is public/MIT-licensed; hardcoding a
+ * bypass secret here would hand it to everyone, not just the owner).
+ *
+ * RULE FOR FUTURE CODE: any billing, rate-limiting, or paywall logic
+ * added to this server MUST call `isOwnerRequest()` first and skip
+ * all limits/charges/metering when it returns true. This function
+ * existing is the guarantee — wire it in before shipping any gate.
+ */
+export function isOwnerRequest(providedKey) {
+    const ownerKey = process.env[OWNER_KEY_ENV_VAR];
+    // If no owner key is configured on the server, there is nothing to
+    // grant bypass against — fail closed (no bypass), not open.
+    if (!ownerKey || !providedKey)
+        return false;
+    const a = Buffer.from(providedKey);
+    const b = Buffer.from(ownerKey);
+    // Constant-time comparison to avoid leaking the key via timing.
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}

dist/services/cargo.d.ts

+import { PackageSummary, LibraryCandidate } from "../types.js";
+/** Fetches real, live crate metadata from crates.io. Throws RegistryError on any failure. */
+export declare function fetchCargoSummary(crateName: string): Promise<PackageSummary>;
+/**
+ * Fetches the real README for a crate at a specific (or latest) version.
+ * crates.io serves this as a redirect to a pre-rendered HTML file, so the
+ * result here is that HTML converted to plain text — not the original
+ * markdown source, which crates.io's API does not expose.
+ */
+export declare function fetchCargoReadme(crateName: string, version?: string): Promise<{
+    readme: string;
+    sourceUrl: string;
+    version: string;
+}>;
+/** Real search against crates.io — used for fuzzy library-name resolution. */
+export declare function searchCargo(query: string, maxResults: number): Promise<LibraryCandidate[]>;

dist/services/cargo.js

+import { CARGO_BASE, CARGO_USER_AGENT, FETCH_TIMEOUT_MS } from "../constants.js";
+import { RegistryError } from "../types.js";
+async function fetchWithTimeout(url, accept = "application/json") {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        return await fetch(url, {
+            signal: controller.signal,
+            headers: { Accept: accept, "User-Agent": CARGO_USER_AGENT },
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Fetches real, live crate metadata from crates.io. Throws RegistryError on any failure. */
+export async function fetchCargoSummary(crateName) {
+    const url = `${CARGO_BASE}/${encodeURIComponent(crateName)}`;
+    const res = await fetchWithTimeout(url);
+    if (res.status === 404) {
+        throw new RegistryError(`Cargo crate '${crateName}' was not found on crates.io.`, 404, url);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`crates.io request failed with status ${res.status}.`, res.status, url);
+    }
+    const doc = (await res.json());
+    return {
+        ecosystem: "cargo",
+        name: doc.crate.name,
+        latest_version: doc.crate.newest_version,
+        description: doc.crate.description ?? null,
+        // crates.io separates "homepage" from "documentation" (usually docs.rs) —
+        // documentation is generally more useful, so prefer it when present.
+        homepage: doc.crate.documentation ?? doc.crate.homepage ?? null,
+        repository: doc.crate.repository ?? null,
+        source_url: url,
+        fetched_at: new Date().toISOString(),
+    };
+}
+/** Strips HTML tags and decodes common entities. crates.io stores READMEs
+ * pre-rendered as HTML (there's no raw-markdown endpoint), so this is the
+ * one ecosystem where the "verbatim" source is HTML, not source markdown.
+ * This is a mechanical markup-removal, not a summarization — no content
+ * is invented or dropped, only tags/entities are converted to plain text. */
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, "")
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, " ")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Fetches the real README for a crate at a specific (or latest) version.
+ * crates.io serves this as a redirect to a pre-rendered HTML file, so the
+ * result here is that HTML converted to plain text — not the original
+ * markdown source, which crates.io's API does not expose.
+ */
+export async function fetchCargoReadme(crateName, version) {
+    const resolvedVersion = version ?? (await fetchCargoSummary(crateName)).latest_version;
+    const url = `${CARGO_BASE}/${encodeURIComponent(crateName)}/${encodeURIComponent(resolvedVersion)}/readme`;
+    // This endpoint's response varies by Accept header (confirmed via crates.io's
+    // own `Vary: accept`) — requesting JSON here returns a small JSON pointer
+    // object instead of following through to the real HTML, so request html/text
+    // explicitly rather than reusing the default Accept used for metadata calls.
+    const res = await fetchWithTimeout(url, "text/html,text/plain,*/*");
+    if (res.status === 404) {
+        throw new RegistryError(`No README found for crate '${crateName}@${resolvedVersion}'.`, 404, url);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`crates.io README request failed with status ${res.status}.`, res.status, url);
+    }
+    const html = await res.text();
+    if (!html || html.trim().length === 0) {
+        throw new RegistryError(`Crate '${crateName}@${resolvedVersion}' has an empty README.`, undefined, url);
+    }
+    // res.url reflects the final URL after the redirect crates.io issues —
+    // that's the real static file this content came from, for verification.
+    return { readme: stripHtml(html), sourceUrl: res.url || url, version: resolvedVersion };
+}
+/** Real search against crates.io — used for fuzzy library-name resolution. */
+export async function searchCargo(query, maxResults) {
+    const url = `${CARGO_BASE}?q=${encodeURIComponent(query)}&per_page=${maxResults}`;
+    const res = await fetchWithTimeout(url);
+    if (!res.ok) {
+        throw new RegistryError(`crates.io search failed with status ${res.status}.`, res.status, url);
+    }
+    const data = (await res.json());
+    return data.crates.map((c) => ({
+        name: c.name,
+        version: c.newest_version,
+        description: c.description ?? null,
+        score: null, // crates.io's search doesn't expose a normalized relevance score
+        url: `https://crates.io/crates/${c.name}`,
+    }));
+}

dist/services/npmSearch.d.ts

+import { LibraryCandidate } from "../types.js";
+/**
+ * Real fuzzy search against npm's actual search index — the same one
+ * npmjs.com's own search box uses. Lets a caller type "react" or "http
+ * client" instead of needing the exact canonical package name.
+ */
+export declare function searchNpm(query: string, maxResults: number): Promise<LibraryCandidate[]>;

dist/services/npmSearch.js

+import { NPM_SEARCH_URL, FETCH_TIMEOUT_MS } from "../constants.js";
+import { RegistryError } from "../types.js";
+async function fetchWithTimeout(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        return await fetch(url, { signal: controller.signal, headers: { Accept: "application/json" } });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Real fuzzy search against npm's actual search index — the same one
+ * npmjs.com's own search box uses. Lets a caller type "react" or "http
+ * client" instead of needing the exact canonical package name.
+ */
+export async function searchNpm(query, maxResults) {
+    const url = `${NPM_SEARCH_URL}?text=${encodeURIComponent(query)}&size=${maxResults}`;
+    const res = await fetchWithTimeout(url);
+    if (!res.ok) {
+        throw new RegistryError(`npm search failed with status ${res.status}.`, res.status, url);
+    }
+    const data = (await res.json());
+    return data.objects.map((o) => ({
+        name: o.package.name,
+        version: o.package.version,
+        description: o.package.description ?? null,
+        score: o.score.final,
+        url: o.package.links?.npm ?? `https://www.npmjs.com/package/${o.package.name}`,
+    }));
+}

dist/services/versionCompare.d.ts

+/**
+ * Best-effort comparison of dotted numeric version strings (e.g. "4.20.0",
+ * "1.2.3"). This is NOT a full semver or PEP 440 implementation — it does
+ * not understand pre-release precedence rules, build metadata, or epoch
+ * segments. For the one thing it's used for here (picking the highest
+ * "fixed_in" version among a small set of real OSV results to fetch docs
+ * for) that's sufficient; it is not used anywhere that requires strict
+ * spec compliance.
+ *
+ * Returns positive if a > b, negative if a < b, 0 if equal or if a
+ * segment can't be compared numerically (never guesses an ordering for
+ * something it can't parse).
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** Returns the highest version in a list per compareVersions, or null if the list is empty. */
+export declare function highestVersion(versions: string[]): string | null;

dist/services/versionCompare.js

+/**
+ * Best-effort comparison of dotted numeric version strings (e.g. "4.20.0",
+ * "1.2.3"). This is NOT a full semver or PEP 440 implementation — it does
+ * not understand pre-release precedence rules, build metadata, or epoch
+ * segments. For the one thing it's used for here (picking the highest
+ * "fixed_in" version among a small set of real OSV results to fetch docs
+ * for) that's sufficient; it is not used anywhere that requires strict
+ * spec compliance.
+ *
+ * Returns positive if a > b, negative if a < b, 0 if equal or if a
+ * segment can't be compared numerically (never guesses an ordering for
+ * something it can't parse).
+ */
+export function compareVersions(a, b) {
+    const stripped = (v) => v.replace(/^v/, "").split(/[+]/)[0]; // drop build metadata
+    const pa = stripped(a).split(/[.\-]/);
+    const pb = stripped(b).split(/[.\-]/);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const na = Number(pa[i]);
+        const nb = Number(pb[i]);
+        if (Number.isNaN(na) || Number.isNaN(nb))
+            continue; // can't compare this segment — move on, don't guess
+        if (na !== nb)
+            return na - nb;
+    }
+    return 0;
+}
+/** Returns the highest version in a list per compareVersions, or null if the list is empty. */
+export function highestVersion(versions) {
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((max, v) => (compareVersions(v, max) > 0 ? v : max), versions[0]);
+}

dist/tools/resolveLibrary.d.ts

+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResolveLibrary(server: McpServer): void;

dist/tools/resolveLibrary.js

+import { z } from "zod";
+import { searchNpm } from "../services/npmSearch.js";
+import { searchCargo } from "../services/cargo.js";
+import { RegistryError } from "../types.js";
+import { NPM_SEARCH_URL, CARGO_BASE } from "../constants.js";
+const InputSchema = z
+    .object({
+    ecosystem: z
+        .enum(["npm", "pypi", "cargo"])
+        .describe("Which registry to search: 'npm', 'pypi', or 'cargo'. Note: PyPI has no official search API (see limitation below)."),
+    query: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe("Natural-language or partial name to resolve, e.g. 'react', 'http client for python', 'serde'."),
+    max_results: z.number().int().min(1).max(10).default(5).describe("Maximum number of candidates to return."),
+})
+    .strict();
+export function registerResolveLibrary(server) {
+    server.registerTool("docs_resolve_library", {
+        title: "Resolve Library Name",
+        description: `Turn a fuzzy or partial name into real, ranked candidate package names, using the registry's own live search index — not a guess at what the package is probably called.
+
+For npm this queries registry.npmjs.org's actual search API (the same one npmjs.com uses). For Cargo this queries crates.io's real search endpoint. For PyPI: there is currently no official PyPI search API (XML-RPC search was permanently disabled in 2022 and never replaced) — calling this with ecosystem 'pypi' returns an explicit message saying so rather than a fabricated or scraped result, along with a suggestion to use the exact package name with docs_get_package_info instead.
+
+Args:
+  - ecosystem ('npm' | 'pypi' | 'cargo')
+  - query (string): the name or description to resolve, e.g. "react" or "async http client"
+  - max_results (number, 1-10, default 5)
+
+Returns JSON with: candidates (array of {name, version, description, score, url}), source_url, fetched_at.
+
+Error Handling:
+  - ecosystem 'pypi' always returns an explanatory message, not an error and not fabricated results
+  - Returns "Error: ..." only for actual npm/crates.io request failures`,
+        inputSchema: InputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        if (params.ecosystem === "pypi") {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "PyPI has no official search API (XML-RPC search was permanently disabled in 2022 and was never replaced with a JSON equivalent). This tool can't resolve fuzzy PyPI names — use the exact package name with docs_get_package_info or docs_get_readme instead.",
+                    },
+                ],
+            };
+        }
+        try {
+            const candidates = params.ecosystem === "npm"
+                ? await searchNpm(params.query, params.max_results)
+                : await searchCargo(params.query, params.max_results);
+            const result = {
+                ecosystem: params.ecosystem,
+                query: params.query,
+                candidates,
+                source_url: params.ecosystem === "npm" ? NPM_SEARCH_URL : CARGO_BASE,
+                fetched_at: new Date().toISOString(),
+            };
+            if (candidates.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No ${params.ecosystem} packages found matching '${params.query}'.` }],
+                    structuredContent: result,
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            if (err instanceof RegistryError) {
+                return {
+                    content: [{ type: "text", text: `Error: ${err.message}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Error: unexpected failure resolving library — ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}

dist/constants.d.ts

 export declare const NPM_REGISTRY_BASE = "https://registry.npmjs.org";
+export declare const NPM_SEARCH_URL = "https://registry.npmjs.org/-/v1/search";
 export declare const JSDELIVR_NPM_BASE = "https://cdn.jsdelivr.net/npm";
 export declare const PYPI_BASE = "https://pypi.org/pypi";
+export declare const CARGO_BASE = "https://crates.io/api/v1/crates";
+export declare const CARGO_USER_AGENT = "scriptdocs-mcp-server (https://github.com/Timwal78/scriptdocs-mcp-server)";
 export declare const OSV_QUERY_URL = "https://api.osv.dev/v1/query";
+export declare const OWNER_KEY_ENV_VAR = "SCRIPTDOCS_OWNER_KEY";
 export declare const CHARACTER_LIMIT = 12000;
+export declare const FIX_DOCS_CHARACTER_LIMIT = 4000;
 export declare const SNIPPET_CONTEXT_CHARS = 600;
 export declare const FETCH_TIMEOUT_MS = 10000;

dist/constants.js

@@ -7,8 +7,20 @@ // Shared constants for ScriptDocs MCP server.
 export const NPM_REGISTRY_BASE = "https://registry.npmjs.org";
+export const NPM_SEARCH_URL = "https://registry.npmjs.org/-/v1/search";
 export const JSDELIVR_NPM_BASE = "https://cdn.jsdelivr.net/npm";
 export const PYPI_BASE = "https://pypi.org/pypi";
+export const CARGO_BASE = "https://crates.io/api/v1/crates";
+// crates.io requires a descriptive User-Agent identifying the client —
+// requests without one are subject to being blocked per their API policy.
+export const CARGO_USER_AGENT = "scriptdocs-mcp-server (https://github.com/Timwal78/scriptdocs-mcp-server)";
 export const OSV_QUERY_URL = "https://api.osv.dev/v1/query";
+// Environment variable holding the founder's always-free access key.
+// See services/access.ts for the enforcement guarantee — this is the
+// name only; the value is a secret, generated once, never committed.
+export const OWNER_KEY_ENV_VAR = "SCRIPTDOCS_OWNER_KEY";
 // Caps how much raw README text we return in a single tool call so agent
 // context windows don't get blown out by huge docs.
 export const CHARACTER_LIMIT = 12000;
+// Smaller cap for the "recommended fix" README bundled alongside a
+// vulnerability report — it's supplementary context, not the primary ask.
+export const FIX_DOCS_CHARACTER_LIMIT = 4000;
 // How many characters of surrounding context to include on each side of a
@@ -15,0 +27,0 @@ // keyword match when extracting a "snippet" from a larger document.

dist/index.js

@@ -9,6 +9,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerCheckVulnerabilities } from "./tools/checkVulnerabilities.js";
+import { registerResolveLibrary } from "./tools/resolveLibrary.js";
+import { isOwnerRequest } from "./services/access.js";
 function buildServer() {
     const server = new McpServer({
         name: "scriptdocs-mcp-server",
-        version: "0.2.0",
+        version: "0.3.0",
     });
@@ -19,2 +21,3 @@ registerGetPackageInfo(server);
     registerCheckVulnerabilities(server);
+    registerResolveLibrary(server);
     return server;
@@ -32,5 +35,14 @@ }
     app.get("/health", (_req, res) => {
-        res.json({ status: "ok", server: "scriptdocs-mcp-server", version: "0.2.0" });
+        res.json({ status: "ok", server: "scriptdocs-mcp-server", version: "0.3.0" });
     });
     app.post("/mcp", async (req, res) => {
+        // No usage limits or billing exist yet — every request is served
+        // identically today. This header exists so that whenever a future
+        // rate-limit/billing layer is added, it has an already-wired,
+        // already-tested identity check to read from — the founder's
+        // always-free access is structural, not an afterthought bolted on
+        // after a paywall ships.
+        const ownerKeyHeader = req.header("x-scriptdocs-owner-key");
+        const accessTier = isOwnerRequest(ownerKeyHeader) ? "owner-unlimited" : "standard";
+        res.setHeader("x-scriptdocs-access-tier", accessTier);
         // Stateless: a fresh server + transport per request avoids request-id
@@ -37,0 +49,0 @@ // collisions and keeps this easy to scale horizontally on Render.

dist/services/osv.js

@@ -7,2 +7,3 @@ import { OSV_QUERY_URL, FETCH_TIMEOUT_MS } from "../constants.js";
     pypi: "PyPI",
+    cargo: "crates.io",
 };
@@ -9,0 +10,0 @@ async function fetchWithTimeout(url, init) {

dist/tools/checkVulnerabilities.js

 import { z } from "zod";
-import { fetchNpmSummary } from "../services/npm.js";
-import { fetchPypiSummary } from "../services/pypi.js";
+import { fetchNpmSummary, fetchNpmReadme } from "../services/npm.js";
+import { fetchPypiSummary, fetchPypiReadme } from "../services/pypi.js";
+import { fetchCargoSummary, fetchCargoReadme } from "../services/cargo.js";
 import { fetchVulnerabilities } from "../services/osv.js";
+import { highestVersion } from "../services/versionCompare.js";
 import { RegistryError } from "../types.js";
-import { OSV_QUERY_URL } from "../constants.js";
+import { OSV_QUERY_URL, FIX_DOCS_CHARACTER_LIMIT } from "../constants.js";
 const InputSchema = z
     .object({
-    ecosystem: z.enum(["npm", "pypi"]).describe("Which package registry the version belongs to: 'npm' or 'pypi'."),
+    ecosystem: z.enum(["npm", "pypi", "cargo"]).describe("Which package registry the version belongs to: 'npm', 'pypi', or 'cargo'."),
     package_name: z.string().min(1).max(214).describe("Exact package name as published on the registry."),
@@ -15,21 +17,37 @@ version: z
         .describe("Specific version to check. Defaults to the current latest published version if omitted."),
+    include_fix_docs: z
+        .boolean()
+        .default(true)
+        .describe("When a vulnerability is found with a known fixed version, also fetch that version's README so the response includes what upgrading actually looks like. Set false to skip the extra fetch."),
 })
     .strict();
+async function fetchReadmeForEcosystem(ecosystem, packageName, version) {
+    if (ecosystem === "npm")
+        return fetchNpmReadme(packageName, version);
+    if (ecosystem === "pypi") {
+        const r = await fetchPypiReadme(packageName, version);
+        return { readme: r.readme, sourceUrl: r.sourceUrl };
+    }
+    const r = await fetchCargoReadme(packageName, version);
+    return { readme: r.readme, sourceUrl: r.sourceUrl };
+}
 export function registerCheckVulnerabilities(server) {
     server.registerTool("docs_check_vulnerabilities", {
         title: "Check Package Vulnerabilities",
-        description: `Check a real, specific package version against OSV.dev — the open, Google-run vulnerability database that aggregates GitHub Security Advisories, PyPA advisories, and npm advisories.
+        description: `Check a real, specific package version against OSV.dev (Google-run, aggregates GitHub/PyPA/npm/RustSec advisories) — and, when a fix exists, automatically fetch that fixed version's README in the same call, so the result is "here's what's wrong" AND "here's exactly what upgrading looks like," not just a CVE list you have to research further yourself.
 
-This is a live query against OSV.dev's public API for the exact package+version given. It never estimates or guesses risk — if OSV has no advisories on record for that version, this correctly reports zero vulnerabilities rather than implying danger that isn't documented.
+This is a live query against OSV.dev's public API for the exact package+version given. It never estimates or guesses risk — if OSV has no advisories on record for that version, this correctly reports zero vulnerabilities rather than implying danger that isn't documented. Note: this tool is more limited than dedicated vulnerability-intelligence tools (e.g. VulnCheck, Snyk) — it reports what OSV.dev has on file, not exploit activity or threat intelligence.
 
 Args:
-  - ecosystem ('npm' | 'pypi')
+  - ecosystem ('npm' | 'pypi' | 'cargo')
   - package_name (string): exact package name
   - version (string, optional): specific version to check; defaults to the latest published version
+  - include_fix_docs (boolean, default true): also fetch the README for the version that fixes the found vulnerabilities
 
-Returns JSON with: vulnerability_count, vulnerabilities (array of {id, summary, severity, aliases, fixed_in, references}), source_url, fetched_at.
+Returns JSON with: vulnerability_count, vulnerabilities (array of {id, summary, severity, aliases, fixed_in, references}), recommended_fix (null, or {version, readme, truncated, source_url} for the version that resolves the found issues), source_url, fetched_at.
 
 Error Handling:
   - Returns "Error: ..." if the package doesn't exist or OSV.dev can't be reached
-  - vulnerability_count: 0 with an empty array is a normal, valid result — not an error`,
+  - vulnerability_count: 0 with an empty array is a normal, valid result — not an error
+  - If fetching the fix's README fails, recommended_fix is null rather than the whole call failing — the vulnerability data itself is never withheld because of it`,
         inputSchema: InputSchema,
@@ -47,4 +65,29 @@ annotations: {
                     ? (await fetchNpmSummary(params.package_name)).latest_version
-                    : (await fetchPypiSummary(params.package_name)).latest_version);
+                    : params.ecosystem === "pypi"
+                        ? (await fetchPypiSummary(params.package_name)).latest_version
+                        : (await fetchCargoSummary(params.package_name)).latest_version);
             const vulnerabilities = await fetchVulnerabilities(params.ecosystem, params.package_name, version);
+            let recommendedFix = null;
+            if (params.include_fix_docs && vulnerabilities.length > 0) {
+                const fixVersions = vulnerabilities.map((v) => v.fixed_in).filter((v) => v !== null);
+                const targetVersion = highestVersion(fixVersions);
+                if (targetVersion && targetVersion !== version) {
+                    try {
+                        const { readme, sourceUrl } = await fetchReadmeForEcosystem(params.ecosystem, params.package_name, targetVersion);
+                        const truncated = readme.length > FIX_DOCS_CHARACTER_LIMIT;
+                        recommendedFix = {
+                            version: targetVersion,
+                            readme: truncated ? readme.slice(0, FIX_DOCS_CHARACTER_LIMIT) + "\n\n...[truncated]" : readme,
+                            truncated,
+                            source_url: sourceUrl,
+                        };
+                    }
+                    catch {
+                        // Fetching the fix's docs failed — leave recommendedFix null.
+                        // The vulnerability report itself is still valid and returned;
+                        // we don't fabricate fix documentation we couldn't retrieve.
+                        recommendedFix = null;
+                    }
+                }
+            }
             const result = {
@@ -56,2 +99,3 @@ ecosystem: params.ecosystem,
                 vulnerabilities,
+                recommended_fix: recommendedFix,
                 source_url: OSV_QUERY_URL,
@@ -58,0 +102,0 @@ fetched_at: new Date().toISOString(),

dist/tools/getPackageInfo.js

 import { z } from "zod";
 import { fetchNpmSummary } from "../services/npm.js";
 import { fetchPypiSummary } from "../services/pypi.js";
+import { fetchCargoSummary } from "../services/cargo.js";
 import { RegistryError } from "../types.js";
 const InputSchema = z
     .object({
-    ecosystem: z.enum(["npm", "pypi"]).describe("Which package registry to query: 'npm' or 'pypi'."),
+    ecosystem: z.enum(["npm", "pypi", "cargo"]).describe("Which package registry to query: 'npm', 'pypi', or 'cargo' (Rust/crates.io)."),
     package_name: z
@@ -12,3 +13,3 @@ .string()
         .max(214)
-        .describe("Exact package name as published on the registry, e.g. 'express' or 'requests'."),
+        .describe("Exact package name as published on the registry, e.g. 'express', 'requests', or 'serde'."),
 })
@@ -19,9 +20,9 @@ .strict();
         title: "Get Package Info",
-        description: `Fetch real, current metadata for a package directly from the npm registry or PyPI JSON API.
+        description: `Fetch real, current metadata for a package directly from the npm registry, PyPI JSON API, or crates.io.
 
-This tool makes a live HTTP request to the actual registry (registry.npmjs.org or pypi.org) at call time. It never returns cached, guessed, or simulated data — if the package doesn't exist, it returns an explicit error rather than a plausible-looking fabrication.
+This tool makes a live HTTP request to the actual registry (registry.npmjs.org, pypi.org, or crates.io) at call time. It never returns cached, guessed, or simulated data — if the package doesn't exist, it returns an explicit error rather than a plausible-looking fabrication.
 
 Args:
-  - ecosystem ('npm' | 'pypi'): which registry to query
-  - package_name (string): exact package name, e.g. "zod" or "fastapi"
+  - ecosystem ('npm' | 'pypi' | 'cargo'): which registry to query
+  - package_name (string): exact package name, e.g. "zod", "fastapi", or "serde"
 
@@ -44,3 +45,5 @@ Returns JSON with: name, latest_version, description, homepage, repository, source_url (the exact registry URL the data came from, for verification), fetched_at (ISO timestamp).
                 ? await fetchNpmSummary(params.package_name)
-                : await fetchPypiSummary(params.package_name);
+                : params.ecosystem === "pypi"
+                    ? await fetchPypiSummary(params.package_name)
+                    : await fetchCargoSummary(params.package_name);
             return {
@@ -47,0 +50,0 @@ content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],

dist/tools/getReadme.js

 import { z } from "zod";
 import { fetchNpmSummary, fetchNpmReadme } from "../services/npm.js";
 import { fetchPypiReadme } from "../services/pypi.js";
+import { fetchCargoReadme } from "../services/cargo.js";
 import { RegistryError } from "../types.js";
@@ -8,3 +9,3 @@ import { CHARACTER_LIMIT } from "../constants.js";
     .object({
-    ecosystem: z.enum(["npm", "pypi"]).describe("Which package registry to query: 'npm' or 'pypi'."),
+    ecosystem: z.enum(["npm", "pypi", "cargo"]).describe("Which package registry to query: 'npm', 'pypi', or 'cargo'."),
     package_name: z.string().min(1).max(214).describe("Exact package name as published on the registry."),
@@ -20,12 +21,12 @@ version: z
         title: "Get Package README",
-        description: `Fetch the real, verbatim README (npm) or long description (PyPI) for a package, straight from the registry — not a summary, not a paraphrase, not AI-generated.
+        description: `Fetch the real README/description for a package, straight from the registry — not a summary, not a paraphrase, not AI-generated.
 
-For npm this reads the registry's stored README, falling back to the published README.md file via jsDelivr if the registry copy is missing. For PyPI this reads the exact long_description shown on the package's PyPI page.
+For npm this reads the registry's stored README, falling back to the published README.md file via jsDelivr if the registry copy is missing (verbatim markdown). For PyPI this reads the exact long_description shown on the package's PyPI page (verbatim). For Cargo (Rust/crates.io) this reads crates.io's stored README — note: crates.io only stores a pre-rendered HTML version, not the original markdown source, so this is that HTML converted to plain text, not byte-for-byte source.
 
 Args:
-  - ecosystem ('npm' | 'pypi')
+  - ecosystem ('npm' | 'pypi' | 'cargo')
   - package_name (string): exact package name
   - version (string, optional): specific version; defaults to latest
 
-Returns JSON with: readme (verbatim text, truncated to ${CHARACTER_LIMIT} chars if longer — check 'truncated'), truncated (boolean), source_url (exact URL fetched, for verification), fetched_at.
+Returns JSON with: readme (truncated to ${CHARACTER_LIMIT} chars if longer — check 'truncated'), truncated (boolean), source_url (exact URL fetched, for verification), fetched_at.
 
@@ -49,6 +50,10 @@ Error Handling:
             }
-            else {
+            else if (params.ecosystem === "pypi") {
                 const { readme, sourceUrl, version } = await fetchPypiReadme(params.package_name, params.version);
                 result = buildResult("pypi", params.package_name, version, readme, sourceUrl);
             }
+            else {
+                const { readme, sourceUrl, version } = await fetchCargoReadme(params.package_name, params.version);
+                result = buildResult("cargo", params.package_name, version, readme, sourceUrl);
+            }
             return {
@@ -55,0 +60,0 @@ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],

dist/tools/searchDocs.js

 import { z } from "zod";
 import { fetchNpmSummary, fetchNpmReadme } from "../services/npm.js";
 import { fetchPypiReadme } from "../services/pypi.js";
+import { fetchCargoReadme } from "../services/cargo.js";
 import { extractSnippets } from "../services/docSearch.js";
@@ -8,3 +9,3 @@ import { RegistryError } from "../types.js";
     .object({
-    ecosystem: z.enum(["npm", "pypi"]).describe("Which package registry to query: 'npm' or 'pypi'."),
+    ecosystem: z.enum(["npm", "pypi", "cargo"]).describe("Which package registry to query: 'npm', 'pypi', or 'cargo'."),
     package_name: z.string().min(1).max(214).describe("Exact package name as published on the registry."),
@@ -28,6 +29,6 @@ query: z
 
-This does keyword matching over the actual fetched document (registry README for npm, long description for PyPI) — it does not summarize or paraphrase, and it does not answer from general knowledge. If no matches are found, it says so rather than guessing at an answer.
+This does keyword matching over the actual fetched document (registry README for npm, long description for PyPI, README-derived text for Cargo) — it does not summarize or paraphrase, and it does not answer from general knowledge. If no matches are found, it says so rather than guessing at an answer.
 
 Args:
-  - ecosystem ('npm' | 'pypi')
+  - ecosystem ('npm' | 'pypi' | 'cargo')
   - package_name (string): exact package name
@@ -61,3 +62,3 @@ - query (string): keyword(s) to search for, e.g. "rate limit" or "async client"
             }
-            else {
+            else if (params.ecosystem === "pypi") {
                 const fetched = await fetchPypiReadme(params.package_name, params.version);
@@ -68,2 +69,8 @@ readme = fetched.readme;
             }
+            else {
+                const fetched = await fetchCargoReadme(params.package_name, params.version);
+                readme = fetched.readme;
+                sourceUrl = fetched.sourceUrl;
+                version = fetched.version;
+            }
             const snippets = extractSnippets(readme, params.query, params.max_snippets);
@@ -70,0 +77,0 @@ const result = {

dist/types.d.ts

@@ -1,2 +0,2 @@
-export type Ecosystem = "npm" | "pypi";
+export type Ecosystem = "npm" | "pypi" | "cargo";
 export interface PackageSummary {
@@ -43,2 +43,8 @@ ecosystem: Ecosystem;
 }
+export interface RecommendedFix {
+    version: string;
+    readme: string;
+    truncated: boolean;
+    source_url: string;
+}
 export interface VulnerabilityCheckResult {
@@ -50,5 +56,20 @@ ecosystem: Ecosystem;
     vulnerabilities: Vulnerability[];
+    recommended_fix: RecommendedFix | null;
     source_url: string;
     fetched_at: string;
 }
+export interface LibraryCandidate {
+    name: string;
+    version: string;
+    description: string | null;
+    score: number | null;
+    url: string;
+}
+export interface ResolveLibraryResult {
+    ecosystem: Ecosystem;
+    query: string;
+    candidates: LibraryCandidate[];
+    source_url: string;
+    fetched_at: string;
+}
 export declare class RegistryError extends Error {
@@ -55,0 +76,0 @@ readonly statusCode?: number | undefined;

package.json

 {
   "name": "@scriptmasterlabs/scriptdocs-mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ScriptMaster Labs docs/context MCP server. Fetches real, verifiable package documentation (npm + PyPI registries) and OSV.dev vulnerability data for AI coding agents. No demo/simulated data.",
@@ -5,0 +5,0 @@ "mcpName": "io.github.Timwal78/scriptdocs-mcp-server",

README.md

@@ -29,7 +29,10 @@ # ScriptDocs MCP Server
 |---|---|
-| `docs_get_package_info` | Live metadata: latest version, description, homepage, repo — from the registry, right now. |
-| `docs_get_readme` | The verbatim README (npm) or long description (PyPI) for a package/version. Supports a specific `version` for both ecosystems. |
-| `docs_search_docs` | Keyword search inside a package's real docs (optionally a specific version), returns verbatim matching snippets with context — not a summary. |
-| `docs_check_vulnerabilities` | Checks a specific package+version against OSV.dev (Google-run, aggregates GitHub/PyPA/npm advisories). Real CVE data, no guessing — zero results means zero advisories on record, not "probably fine." |
+| `docs_get_package_info` | Live metadata: latest version, description, homepage, repo — npm, PyPI, or Cargo (crates.io), right now. |
+| `docs_get_readme` | The verbatim README (npm), long description (PyPI), or README-derived text (Cargo — see note below) for a package/version. |
+| `docs_search_docs` | Keyword search inside a package's real docs (any of the 3 ecosystems, optionally a specific version), returns verbatim matching snippets with context — not a summary. |
+| `docs_check_vulnerabilities` | Checks a specific package+version against OSV.dev. When a fix exists, **automatically fetches that fixed version's README in the same call** — "here's what's wrong" and "here's what upgrading looks like," one round trip. |
+| `docs_resolve_library` | Fuzzy name → real candidates, via npm's and crates.io's actual search APIs. PyPI has no official search API (confirmed: XML-RPC search was killed in 2022, never replaced) — calling this for PyPI returns an honest explanation, not a scraped or fabricated result. |
 
+**Note on Cargo READMEs**: crates.io stores READMEs pre-rendered as HTML, not the original markdown source — there's no raw-source endpoint. `docs_get_readme`/`docs_search_docs` return that HTML converted to plain text (tags stripped, entities decoded) — a mechanical transformation, not a summary; no content is invented or dropped.
+
 ## Project layout
@@ -48,4 +51,8 @@
 │   │   ├── npm.ts        # real npm registry client
+│   │   ├── npmSearch.ts  # real npm search API (fuzzy resolution)
 │   │   ├── pypi.ts       # real PyPI registry client (supports version pinning)
+│   │   ├── cargo.ts      # real crates.io client (metadata, readme, search)
 │   │   ├── osv.ts        # real OSV.dev vulnerability database client
+│   │   ├── versionCompare.ts  # best-effort numeric version comparator
+│   │   ├── access.ts     # founder always-free guarantee
 │   │   └── docSearch.ts  # keyword/snippet extraction over fetched text
@@ -56,3 +63,4 @@ │   └── tools/
 │       ├── searchDocs.ts
-│       └── checkVulnerabilities.ts
+│       ├── checkVulnerabilities.ts
+│       └── resolveLibrary.ts
 └── dist/                 # build output (git-ignored)
@@ -104,13 +112,21 @@ ```
 
-- `docs_get_package_info` → `express` (npm) returned real current version
-  and metadata straight from `registry.npmjs.org`.
-- `docs_get_readme` → `zod` (npm, via jsDelivr fallback), `requests` (PyPI,
-  latest), and `requests==2.28.0` (PyPI, version-pinned) all returned real,
-  verbatim README text from the exact version requested.
-- `docs_search_docs` → keyword search over the real zod README returned
-  verbatim matching context.
-- `docs_check_vulnerabilities` → `express@4.17.1` correctly returned 2 real
-  advisories (incl. CVE-2024-43796) from OSV.dev; `express@5.2.1` (current)
-  correctly returned zero — verified against the live OSV.dev API, not
-  simulated.
+- `docs_get_package_info` → `express` (npm), `serde` (cargo) returned real
+  current metadata straight from their respective registries.
+- `docs_get_readme` → `zod` (npm, jsDelivr fallback), `requests` (PyPI,
+  latest + version-pinned), and `serde` (cargo) all returned real README
+  content. The cargo path hit a real bug during testing — crates.io's
+  README endpoint varies its response by `Accept` header and was
+  returning a JSON pointer instead of HTML — caught and fixed, verified
+  again after the fix.
+- `docs_search_docs` → keyword search over real docs verified across
+  npm and cargo.
+- `docs_check_vulnerabilities` → `express@4.17.1` correctly returned 2
+  real advisories (incl. CVE-2024-43796) *and* automatically fetched the
+  real README for `4.20.0` (the fixed version) in the same call — the
+  vuln-to-fix bridge, verified working end-to-end.
+- `docs_resolve_library` → real fuzzy search verified for npm ("react"
+  → react, react-is, ...) and cargo ("http client" → real candidates).
+  PyPI correctly returns an honest limitation message instead of a
+  fabricated result (verified: PyPI has had no official search API
+  since 2022).
 - Nonexistent package name → correctly returns an explicit
@@ -121,2 +137,25 @@ `isError: true` response instead of fabricating a plausible answer.
 
+## Founder always-free guarantee
+
+ScriptMaster Labs (you) always gets full, unmetered, free access to every
+tool this server exposes — no matter what paid tiers get built later.
+This is baked into the architecture now, before any billing exists, not
+retrofitted after the fact:
+
+- `src/services/access.ts` exports `isOwnerRequest()`, checked against a
+  secret in the `SCRIPTDOCS_OWNER_KEY` environment variable (never
+  hardcoded — this repo is public, so a hardcoded bypass would give
+  everyone free access, not just you).
+- The HTTP transport already tags every request with an
+  `x-scriptdocs-access-tier` response header (`owner-unlimited` or
+  `standard`) — verified working, not just written.
+- **Rule for any future billing/rate-limit code**: call
+  `isOwnerRequest()` first and skip all limits/charges when it returns
+  true.
+
+To use it once deployed: set `SCRIPTDOCS_OWNER_KEY` as an environment
+variable on your Render service, then send requests with header
+`x-scriptdocs-owner-key: <that value>`. Keep the value secret — it's
+not in this repo, and shouldn't be.
+
 ## Getting listed as a real alternative (not hype — the actual mechanics)
@@ -181,17 +220,28 @@
 
-1. **Licensing/monetization** — needs your real Stripe keys and a decision
-   on free-tier call limits before anything gets built here. I won't wire
-   up fake gating that pretends to work.
-2. **More ecosystems** — Cargo (Rust), Go modules, RubyGems would follow
-   the same `services/*.ts` pattern already established for npm/PyPI.
-3. **Versioned doc pages** (not just README) — would need per-package doc
-   site scraping, which is a bigger lift than the registry APIs used here.
-4. **Caching layer** — currently every call hits the live registry fresh
-   (correct for accuracy, but means repeated calls for the same package in
-   one session re-fetch). A short in-memory TTL cache would cut latency
-   without sacrificing truthfulness — not yet built.
-5. **Remote (HTTP) registry listing** — the registry also supports a
-   `remotes` entry pointing at a live URL (same pattern as your other
-   Render-hosted MCP servers), which can be added to `server.json`
-   alongside the npm `packages` entry once this is actually deployed to
-   Render with a public URL.
+1. **Licensing/monetization** — needs your real Stripe/x402 decisions
+   and pricing before anything gets built here. Research so far:
+   Context7 (the main comparable) keeps public docs lookup free
+   indefinitely and monetizes private-library support + team seats +
+   compliance, not public lookups. Freemium dev-tools convert
+   free→paid at 2-4% typically (8-12% is considered great).
+2. **Private/internal library support** — the one proven lever in this
+   category (see above) — needs a hosted service (see #6 below), not
+   yet built.
+3. **PyPI fuzzy resolution** — not buildable against PyPI's official
+   API (confirmed: no search API has existed since 2022). Only real
+   option is leaning on an unofficial third-party index/mirror, with
+   the tradeoffs that implies.
+4. **Go modules** — metadata support (versions, checksums) would follow
+   the same pattern as npm/PyPI/Cargo. Fuzzy resolution would not:
+   confirmed `proxy.golang.org` has no search endpoint at all.
+5. **Real relevance ranking** (semantic search, not keyword substring)
+   — buildable, but the real version needs an embeddings API (real
+   ongoing cost) and a vector store — a spend decision, not built yet.
+6. **Remote (HTTP) registry listing + hosted deployment** — needed as
+   the foundation for private-library support and any future rate
+   limiting; `server.json` supports adding a `remotes` entry once this
+   is deployed to Render with a public URL.
+7. **Caching layer** — currently every call hits the live registry fresh
+   (correct for accuracy, but means repeated calls for the same package
+   in one session re-fetch). A short in-memory TTL cache would cut
+   latency without sacrificing truthfulness — not yet built.

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

69575

62.61%

Number of package files

34

41.67%

Lines of code

1220

60.1%

Number of lines in readme file

242

26.04%

Worsened metrics

Number of low supply chain risk alerts

7

133.33%

Number of medium supply chain risk alerts

5

66.67%

No dependency changes