@quantakrypto/mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,421 @@
+/**
+ * quantakrypto MCP tools, backed by {@link @quantakrypto/core}.
+ *
+ * Every tool returns an MCP {@link ToolResult} ({ content, isError? }). Because
+ * `@quantakrypto/core` is still partly stubbed (several functions throw "not
+ * implemented"), each handler runs core calls through {@link safe} so a missing
+ * implementation surfaces as a readable `isError` tool result instead of a
+ * protocol-level crash. When core lands, the tools work unchanged.
+ */
+import { VERSION, buildInventory, detectors, remediationFor, scan, toCbom, } from "@quantakrypto/core";
+import { errorResult, textResult } from "./protocol.js";
+import { resolveRule } from "./rules.js";
+/** Severity order for stable, human-friendly summaries. */
+const SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];
+/** All classical algorithm families we can advise on, used for validation/help. */
+const ALGORITHM_FAMILIES = [
+    "RSA",
+    "ECDH",
+    "ECDSA",
+    "EdDSA",
+    "DH",
+    "DSA",
+    "X25519",
+    "ECIES",
+    "unknown",
+];
+/**
+ * Run a possibly-throwing core call, mapping any failure to an error tool
+ * result. Returns either the value or a {@link ToolResult} sentinel.
+ */
+async function safe(label, fn) {
+    try {
+        return { ok: true, value: await fn() };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ok: false, result: errorResult(`${label} failed: ${detail}`) };
+    }
+}
+/** Map a free-text algorithm string onto a known {@link AlgorithmFamily}. */
+function normalizeAlgorithm(input) {
+    const cleaned = input
+        .trim()
+        .toUpperCase()
+        .replace(/[\s_-]+/g, "");
+    for (const fam of ALGORITHM_FAMILIES) {
+        if (fam.toUpperCase() === cleaned)
+            return fam;
+    }
+    // Common aliases / families folded into the canonical set.
+    if (cleaned.startsWith("RSA"))
+        return "RSA";
+    if (cleaned.includes("ECDSA"))
+        return "ECDSA";
+    if (cleaned.includes("ED25519") || cleaned.includes("EDDSA"))
+        return "EdDSA";
+    if (cleaned.includes("X25519") || cleaned.includes("CURVE25519"))
+        return "X25519";
+    if (cleaned.includes("ECDH"))
+        return "ECDH";
+    if (cleaned.includes("ECIES"))
+        return "ECIES";
+    if (cleaned === "DH" || cleaned.includes("DIFFIEHELLMAN"))
+        return "DH";
+    if (cleaned === "DSA")
+        return "DSA";
+    return "unknown";
+}
+/** Render a scan result as a compact human-readable summary. */
+function summarizeScan(result) {
+    const inv = result.inventory;
+    const lines = [];
+    lines.push(`quantakrypto scan of ${result.root}`);
+    lines.push(`Files scanned: ${result.filesScanned}`);
+    lines.push(`Findings: ${result.findings.length}`);
+    lines.push(`Readiness score: ${inv.readinessScore}/100`);
+    lines.push(`Harvest-now-decrypt-later exposure: ${inv.hndlCount} finding(s)`);
+    const sev = SEVERITY_ORDER.filter((s) => (inv.bySeverity[s] ?? 0) > 0)
+        .map((s) => `${s}: ${inv.bySeverity[s]}`)
+        .join(", ");
+    if (sev)
+        lines.push(`By severity: ${sev}`);
+    const algos = Object.entries(inv.byAlgorithm)
+        .filter(([, n]) => (n ?? 0) > 0)
+        .map(([a, n]) => `${a}: ${n}`)
+        .join(", ");
+    if (algos)
+        lines.push(`By algorithm: ${algos}`);
+    if (result.findings.length > 0) {
+        lines.push("");
+        lines.push("Top findings:");
+        const top = [...result.findings]
+            .sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity))
+            .slice(0, 20);
+        for (const f of top) {
+            const loc = `${f.location.file}:${f.location.line}`;
+            lines.push(`- [${f.severity}] ${f.ruleId} (${loc}) — ${f.message}`);
+        }
+        if (result.findings.length > top.length) {
+            lines.push(`… and ${result.findings.length - top.length} more.`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+const scanPathTool = {
+    name: "scan_path",
+    description: "Scan a file or directory for classical (quantum-vulnerable) asymmetric " +
+        "cryptography using quantakrypto. Returns a readiness summary and findings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute or relative path to a file or directory to scan.",
+            },
+            format: {
+                type: "string",
+                enum: ["summary", "json"],
+                description: "Output format: 'summary' (default) for readable text, 'json' for the raw ScanResult.",
+            },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const path = args.path;
+        if (typeof path !== "string" || path.length === 0) {
+            return errorResult("scan_path requires a non-empty 'path' string.");
+        }
+        const format = args.format === "json" ? "json" : "summary";
+        const scanned = await safe("scan", () => scan({ root: path }));
+        if (!scanned.ok)
+            return scanned.result;
+        const result = scanned.value;
+        if (format === "json") {
+            return textResult(JSON.stringify(result, null, 2));
+        }
+        return textResult(summarizeScan(result));
+    },
+};
+const inventoryCryptoTool = {
+    name: "inventory_crypto",
+    description: "Produce a post-quantum readiness inventory for a path: a 0-100 readiness " +
+        "score plus counts of cryptographic findings by algorithm, category, and severity.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute or relative path to a file or directory to inventory.",
+            },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const path = args.path;
+        if (typeof path !== "string" || path.length === 0) {
+            return errorResult("inventory_crypto requires a non-empty 'path' string.");
+        }
+        const scanned = await safe("scan", () => scan({ root: path }));
+        if (!scanned.ok)
+            return scanned.result;
+        const result = scanned.value;
+        // Prefer a freshly built inventory from findings; fall back to the scan's own.
+        const built = await safe("buildInventory", () => buildInventory(result.findings));
+        const inventory = built.ok ? built.value : result.inventory;
+        const lines = [];
+        lines.push(`Post-quantum readiness for ${result.root}`);
+        lines.push(`Readiness score: ${inventory.readinessScore}/100`);
+        lines.push(`HNDL exposure: ${inventory.hndlCount}`);
+        lines.push("");
+        lines.push("By algorithm:");
+        for (const [algo, n] of Object.entries(inventory.byAlgorithm)) {
+            if ((n ?? 0) > 0)
+                lines.push(`  ${algo}: ${n}`);
+        }
+        lines.push("By category:");
+        for (const [cat, n] of Object.entries(inventory.byCategory)) {
+            if ((n ?? 0) > 0)
+                lines.push(`  ${cat}: ${n}`);
+        }
+        lines.push("By severity:");
+        for (const sev of SEVERITY_ORDER) {
+            const n = inventory.bySeverity[sev] ?? 0;
+            if (n > 0)
+                lines.push(`  ${sev}: ${n}`);
+        }
+        return {
+            content: [
+                { type: "text", text: lines.join("\n") },
+                { type: "text", text: JSON.stringify(inventory, null, 2) },
+            ],
+        };
+    },
+};
+const explainFindingTool = {
+    name: "explain_finding",
+    description: "Explain a quantakrypto finding and its post-quantum remediation. Provide a " +
+        "ruleId (e.g. 'forge-rsa-keygen', 'elliptic-ec', 'node-rsa', 'pem-ec-private-key') " +
+        "and/or an algorithm (e.g. 'RSA', 'ECDSA'). The ruleId is resolved against the " +
+        "core detector set, so library and config rules explain correctly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ruleId: {
+                type: "string",
+                description: "The finding's rule id, matching a detector id prefix.",
+            },
+            algorithm: {
+                type: "string",
+                description: "The classical algorithm family involved (e.g. RSA, ECDH, ECDSA).",
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const ruleId = typeof args.ruleId === "string" ? args.ruleId.trim() : "";
+        const algoInput = typeof args.algorithm === "string" ? args.algorithm.trim() : "";
+        if (!ruleId && !algoInput) {
+            return errorResult("explain_finding requires at least one of 'ruleId' or 'algorithm'.");
+        }
+        const lines = [];
+        // Resolve the rule against core's actual detector set/registry (P0-5),
+        // not by a fragile id-prefix match. Library rules (forge-*, elliptic-ec,
+        // node-rsa, …) resolve to their `crypto-libs` detector and carry their
+        // algorithm, so they now explain correctly.
+        let resolvedAlgorithm;
+        if (ruleId) {
+            const resolved = resolveRule(ruleId);
+            resolvedAlgorithm = resolved.algorithm;
+            lines.push(`Rule: ${ruleId}`);
+            if (resolved.detector) {
+                lines.push(`Detector: ${resolved.detector.id} — ${resolved.detector.description}`);
+            }
+            else if (resolved.via === "unresolved") {
+                lines.push("No matching detector found in the catalog (rule may be unknown to this core version).");
+            }
+        }
+        // Prefer an explicit algorithm; otherwise use the one the rule resolved to.
+        const algorithm = algoInput
+            ? normalizeAlgorithm(algoInput)
+            : resolvedAlgorithm && resolvedAlgorithm !== "unknown"
+                ? resolvedAlgorithm
+                : undefined;
+        if (algorithm) {
+            if (lines.length)
+                lines.push("");
+            lines.push(`Algorithm: ${algorithm}`);
+            const rem = await safe("remediationFor", () => remediationFor(algorithm));
+            if (rem.ok && rem.value) {
+                lines.push(`Why it matters: ${algorithm} relies on hardness assumptions (integer factorization / discrete log) that Shor's algorithm breaks on a cryptographically-relevant quantum computer.`);
+                lines.push(`Recommendation: ${rem.value.recommendation}`);
+                lines.push(`Detail: ${rem.value.detail}`);
+            }
+            else if (rem.ok) {
+                lines.push("No specific remediation is registered for this algorithm.");
+            }
+            else {
+                return rem.result;
+            }
+        }
+        return textResult(lines.join("\n"));
+    },
+};
+const suggestHybridTool = {
+    name: "suggest_hybrid",
+    description: "Recommend a post-quantum / hybrid migration. Provide an 'algorithm' " +
+        "(e.g. RSA, ECDH, ECDSA) or free-text 'context' describing the usage.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            algorithm: {
+                type: "string",
+                description: "Classical algorithm family to migrate away from.",
+            },
+            context: {
+                type: "string",
+                description: "Free-text description of the cryptographic usage (used when no algorithm is given).",
+            },
+        },
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const algoInput = typeof args.algorithm === "string" ? args.algorithm.trim() : "";
+        const context = typeof args.context === "string" ? args.context.trim() : "";
+        if (!algoInput && !context) {
+            return errorResult("suggest_hybrid requires either 'algorithm' or 'context'.");
+        }
+        const algorithm = normalizeAlgorithm(algoInput || context);
+        const lines = [];
+        lines.push(`Migration guidance for: ${algoInput || context}`);
+        lines.push(`Detected family: ${algorithm}`);
+        const rem = await safe("remediationFor", () => remediationFor(algorithm));
+        if (rem.ok && rem.value) {
+            lines.push(`Recommended replacement: ${rem.value.recommendation}`);
+            lines.push(`Rationale: ${rem.value.detail}`);
+        }
+        else {
+            // Static fallback table so the tool stays useful even with a stubbed core.
+            lines.push(...staticHybridAdvice(algorithm));
+        }
+        lines.push("");
+        lines.push("Hybrid migrations combine a classical primitive with a NIST PQC algorithm " +
+            "so security holds if either survives. Roll out hybrids first, then drop the " +
+            "classical half once the PQC side is proven in your environment.");
+        return textResult(lines.join("\n"));
+    },
+};
+/** Built-in PQC guidance used when core's remediation table is unavailable. */
+function staticHybridAdvice(algorithm) {
+    switch (algorithm) {
+        case "RSA":
+        case "ECIES":
+            return [
+                "Recommended replacement: ML-KEM-768 for key establishment (hybrid X25519MLKEM768).",
+                "For signatures use ML-DSA-65 (Dilithium) or SLH-DSA (SPHINCS+) where statelessness matters.",
+            ];
+        case "ECDH":
+        case "DH":
+        case "X25519":
+            return [
+                "Recommended replacement: hybrid X25519MLKEM768 key exchange (ML-KEM-768 + X25519).",
+                "Supported in modern TLS 1.3 stacks; prefer the hybrid named group over bare ML-KEM.",
+            ];
+        case "ECDSA":
+        case "EdDSA":
+        case "DSA":
+            return [
+                "Recommended replacement: ML-DSA-65 (Dilithium) for general signatures.",
+                "Use SLH-DSA (SPHINCS+) for long-lived roots or where a stateless hash-based scheme is preferred.",
+            ];
+        default:
+            return [
+                "Recommended replacement: adopt NIST PQC — ML-KEM for key establishment, ML-DSA for signatures.",
+                "Deploy as hybrids (classical + PQC) during transition.",
+            ];
+    }
+}
+const listRulesTool = {
+    name: "list_rules",
+    description: "List the quantakrypto detector catalog: every detector id and what it looks for.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    async handler() {
+        const detectorList = await safe("detectors", () => detectors);
+        if (!detectorList.ok)
+            return detectorList.result;
+        const catalog = detectorList.value.map((d) => ({ id: d.id, description: d.description }));
+        if (catalog.length === 0) {
+            return textResult("No detectors are registered in @quantakrypto/core yet (the catalog is empty).");
+        }
+        const human = catalog.map((d) => `- ${d.id}: ${d.description}`).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `quantakrypto detector catalog (${catalog.length} rules):\n${human}`,
+                },
+                { type: "text", text: JSON.stringify(catalog, null, 2) },
+            ],
+        };
+    },
+};
+const generateCbomTool = {
+    name: "generate_cbom",
+    description: "Scan a path and emit a CycloneDX 1.6 Cryptographic Bill of Materials (CBOM) " +
+        "of the classical cryptographic assets found, for compliance / supply-chain " +
+        "tooling. Reads the filesystem, so it is gated like scan_path over HTTP.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute or relative path to a file or directory to inventory.",
+            },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const path = args.path;
+        if (typeof path !== "string" || path.length === 0) {
+            return errorResult("generate_cbom requires a non-empty 'path' string.");
+        }
+        const scanned = await safe("scan", () => scan({ root: path }));
+        if (!scanned.ok)
+            return scanned.result;
+        const cbom = await safe("toCbom", () => toCbom(scanned.value));
+        if (!cbom.ok)
+            return cbom.result;
+        return textResult(JSON.stringify(cbom.value, null, 2));
+    },
+};
+/**
+ * Tools that read arbitrary filesystem paths. Disabled by default on the HTTP
+ * transport (see {@link ./http.ts}) because a hosted endpoint must not be an
+ * arbitrary-file-read oracle (security audit Q-01). The stdio transport, which
+ * trusts the local user, always exposes them.
+ */
+export const FS_TOOL_NAMES = ["scan_path", "inventory_crypto", "generate_cbom"];
+/** All quantakrypto MCP tools, in a stable order. */
+export const quantakryptoTools = [
+    scanPathTool,
+    inventoryCryptoTool,
+    explainFindingTool,
+    suggestHybridTool,
+    listRulesTool,
+    generateCbomTool,
+];
+/** The core version these tools are built against (re-exported for diagnostics). */
+export const CORE_VERSION = VERSION;
+/** Exposed for tests and advanced callers. */
+export const __test = { normalizeAlgorithm, summarizeScan, staticHybridAdvice };
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+## `transcript.jsonl`
+
+A sample MCP session against the quantakrypto server, one JSON object per line. Each
+line has a `direction` (`client→server` / `server→client`), an optional `note`,
+and the JSON-RPC `message` actually exchanged.
+
+It walks through a full lifecycle:
+
+1. `initialize` handshake (and its response advertising `serverInfo` + capabilities)
+2. the `notifications/initialized` notification (no response is returned)
+3. a `ping` keepalive
+4. `tools/list` (the complete tool catalog with input schemas)
+5. two `tools/call` invocations (`suggest_hybrid`, `explain_finding`)
+6. an error case: an unknown method returning JSON-RPC error `-32601`
+
+The `direction`/`note` wrappers are illustrative metadata; on the wire only the
+`message` payloads are sent (newline-delimited over stdio, or as the `POST /mcp`
+body over HTTP).
+
+The `explain_finding` / detector text shown reflects a populated `@quantakrypto/core`;
+with the current stub the catalog may be empty, but the protocol shapes are
+identical.
+
+### Replaying over HTTP
+
+```bash
+PORT=3000 node ../dist/http.js &
+
+curl -s localhost:3000/mcp -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}' | jq
+
+curl -s localhost:3000/mcp -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"suggest_hybrid","arguments":{"algorithm":"RSA"}}}' | jq
+```

package/examples/transcript.jsonl

@@ -0,0 +1,13 @@
+{"direction":"client→server","note":"handshake","message":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"quantakrypto","version":"0.1.0"},"instructions":"quantakrypto checks code for quantum-vulnerable cryptography and recommends post-quantum (NIST PQC) migrations. Use scan_path / inventory_crypto to assess a path, list_rules to see detectors, and explain_finding / suggest_hybrid for remediation guidance."}}}
+{"direction":"client→server","note":"notification — no response is sent","message":{"jsonrpc":"2.0","method":"notifications/initialized"}}
+{"direction":"client→server","note":"liveness check","message":{"jsonrpc":"2.0","id":2,"method":"ping"}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":2,"result":{}}}
+{"direction":"client→server","note":"discover tools","message":{"jsonrpc":"2.0","id":3,"method":"tools/list"}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":3,"result":{"tools":[{"name":"explain_finding","description":"Explain a quantakrypto finding and its post-quantum remediation. Provide a ruleId (e.g. 'rsa-keygen') and/or an algorithm (e.g. 'RSA', 'ECDSA').","inputSchema":{"type":"object","properties":{"ruleId":{"type":"string","description":"The finding's rule id, matching a detector id prefix."},"algorithm":{"type":"string","description":"The classical algorithm family involved (e.g. RSA, ECDH, ECDSA)."}},"additionalProperties":false}},{"name":"inventory_crypto","description":"Produce a post-quantum readiness inventory for a path: a 0-100 readiness score plus counts of cryptographic findings by algorithm, category, and severity.","inputSchema":{"type":"object","properties":{"path":{"type":"string","description":"Absolute or relative path to a file or directory to inventory."}},"required":["path"],"additionalProperties":false}},{"name":"list_rules","description":"List the quantakrypto detector catalog: every detector id and what it looks for.","inputSchema":{"type":"object","properties":{},"additionalProperties":false}},{"name":"scan_path","description":"Scan a file or directory for classical (quantum-vulnerable) asymmetric cryptography using quantakrypto. Returns a readiness summary and findings.","inputSchema":{"type":"object","properties":{"path":{"type":"string","description":"Absolute or relative path to a file or directory to scan."},"format":{"type":"string","enum":["summary","json"],"description":"Output format: 'summary' (default) for readable text, 'json' for the raw ScanResult."}},"required":["path"],"additionalProperties":false}},{"name":"suggest_hybrid","description":"Recommend a post-quantum / hybrid migration. Provide an 'algorithm' (e.g. RSA, ECDH, ECDSA) or free-text 'context' describing the usage.","inputSchema":{"type":"object","properties":{"algorithm":{"type":"string","description":"Classical algorithm family to migrate away from."},"context":{"type":"string","description":"Free-text description of the cryptographic usage (used when no algorithm is given)."}},"additionalProperties":false}}]}}}
+{"direction":"client→server","note":"call a tool","message":{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"suggest_hybrid","arguments":{"algorithm":"RSA"}}}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"Migration guidance for: RSA\nDetected family: RSA\nRecommended replacement: ML-KEM-768 for key establishment (hybrid X25519MLKEM768).\nFor signatures use ML-DSA-65 (Dilithium) or SLH-DSA (SPHINCS+) where statelessness matters.\n\nHybrid migrations combine a classical primitive with a NIST PQC algorithm so security holds if either survives. Roll out hybrids first, then drop the classical half once the PQC side is proven in your environment."}]}}}
+{"direction":"client→server","note":"explain a finding","message":{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"explain_finding","arguments":{"ruleId":"rsa-keygen","algorithm":"RSA"}}}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":5,"result":{"content":[{"type":"text","text":"Rule: rsa-keygen\nDetector: rsa — detects RSA key generation and usage.\n\nAlgorithm: RSA\nWhy it matters: RSA relies on hardness assumptions (integer factorization / discrete log) that Shor's algorithm breaks on a cryptographically-relevant quantum computer.\nRecommendation: ML-KEM-768 (hybrid X25519MLKEM768)\nDetail: Replace RSA key transport/encryption with ML-KEM; deploy as a hybrid during transition."}]}}}
+{"direction":"client→server","note":"error case — unknown method","message":{"jsonrpc":"2.0","id":6,"method":"resources/list"}}
+{"direction":"server→client","message":{"jsonrpc":"2.0","id":6,"error":{"code":-32601,"message":"method not found: resources/list"}}}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@quantakrypto/mcp",
+  "version": "0.1.0",
+  "description": "quantakrypto MCP — post-quantum readiness for AI coding agents via the Model Context Protocol. Zero runtime dependencies (stdio JSON-RPC implemented in-house).",
+  "license": "Apache-2.0",
+  "author": "Dandelion Labs <hello@dandelionlabs.io> (https://dandelionlabs.io)",
+  "homepage": "https://github.com/dandelionlabs-io/qproof-tools/tree/main/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dandelionlabs-io/qproof-tools.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/dandelionlabs-io/qproof-tools/issues"
+  },
+  "type": "module",
+  "bin": {
+    "quantakrypto-mcp": "./dist/stdio.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "HOSTING.md",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@quantakrypto/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}