qopanza-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Gsente LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,145 @@
+# Qopanza MCP server
+
+Lets an AI coding agent — Claude Code, Cursor, Windsurf, Claude Desktop —
+scan an app for exposed secrets and open databases, and then fix what it
+finds.
+
+The point is that the person using it never sees this. They type:
+
+> check my app is secure before I launch
+
+and the agent calls `scan_app_url`, gets structured findings back, calls
+`get_fixes`, and applies the edits. No dashboard, no report to read, no
+signup flow in the middle of their work.
+
+## Why this exists rather than a CLI
+
+The audience is someone who built an app on Lovable, Bolt, v0 or Replit.
+They do not have a terminal habit, and a scan *report* is homework — a
+list of things to go and do, in vocabulary they do not have. An agent
+with these tools skips the report entirely and changes the code.
+
+That also fixes the hardest part of the product: explaining what row-level
+security is. The agent does not need it explained. It needs a policy and a
+file to put it in, which is what `get_fixes` returns.
+
+## Install
+
+Nothing to clone or build. Your agent runs it with `npx`, which fetches
+the published package the first time. Node 18 or newer.
+
+**Claude Code:**
+
+```bash
+claude mcp add qopanza -e QOPANZA_API_KEY=qsk_... -- npx -y qopanza-mcp
+```
+
+**Codex** (OpenAI):
+
+```bash
+codex mcp add qopanza --env QOPANZA_API_KEY=qsk_... -- npx -y qopanza-mcp
+```
+
+or by hand in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.qopanza]
+command = "npx"
+args = ["-y", "qopanza-mcp"]
+
+[mcp_servers.qopanza.env]
+QOPANZA_API_KEY = "qsk_..."
+```
+
+**Grok Build** (xAI) — in `~/.grok/config.toml`. Grok expands
+`${QOPANZA_API_KEY}` from your shell at start-up, so the key never has to
+be written into the file. `grok mcp doctor qopanza` checks the connection.
+
+```toml
+[mcp_servers.qopanza]
+command = "npx"
+args = ["-y", "qopanza-mcp"]
+env = { QOPANZA_API_KEY = "${QOPANZA_API_KEY}" }
+```
+
+**Cursor** (`~/.cursor/mcp.json`), **Windsurf** (`~/.codeium/windsurf/mcp_config.json`)
+and **Claude Desktop** (`claude_desktop_config.json`) all take the same
+block:
+
+```json
+{
+  "mcpServers": {
+    "qopanza": {
+      "command": "npx",
+      "args": ["-y", "qopanza-mcp"],
+      "env": {
+        "QOPANZA_API_KEY": "qsk_..."
+      }
+    }
+  }
+}
+```
+
+Then ask your agent something like *"scan https://myapp.com for exposed
+secrets and fix what you find"*.
+
+`QOPANZA_API_KEY` comes from **API Keys** in the dashboard; a free
+account is enough for every tool except `get_fixes`. The key lives in
+your agent's local config, never in your project's code. `QOPANZA_BASE_URL`
+defaults to `https://api.qopanza.com/v1`; set it only for a self-hosted
+deployment.
+
+### Lovable, Replit and other cloud agents: the hosted server
+
+Agents that run in the vendor's cloud cannot launch `npx`. They connect to
+a server by URL instead, and Qopanza hosts one with the same four tools:
+
+```
+https://api.qopanza.com/mcp
+```
+
+Authenticate with your API key, either as `Authorization: Bearer qsk_...`
+or as an `X-API-Key: qsk_...` header.
+
+- **Lovable:** Connectors → **+** → **MCP server**. Server name `Qopanza`,
+  the URL above, and choose **Bearer token or API key** with your key.
+- **Replit:** Integrations → MCP Servers → **+ Add MCP server**. Display
+  name `Qopanza`, the URL above as **MCP Server URL**, then **Advanced
+  settings** → header `X-API-Key` with your key → **Test & save**.
+
+### From source
+
+For working on the server itself:
+
+```bash
+cd mcp-server
+npm install
+npm run build
+claude mcp add qopanza -- node "$(pwd)/dist/index.js"
+```
+
+## Tools
+
+| Tool | Plan | What it does |
+|---|---|---|
+| `scan_app_url` | Free | Fetches a deployed site and reads the JavaScript it serves. Anything found is already public. |
+| `scan_app_code` | Free | Scans one file's contents — what an agent calls while editing. |
+| `get_fixes` | **App Security** or above | Turns findings into exact edits, config files and SQL policies. |
+| `scan_crypto` | Free | The quantum-vulnerability scan, for code with its own cryptography. |
+
+Every tool needs `QOPANZA_API_KEY`. Without one the server does not fail
+silently: the agent is told the key is missing and where to get it. (The
+no-account scan on qopanza.com/scan is a separate, rate-limited endpoint
+this server does not use.)
+
+## The thing an agent must not get wrong
+
+`get_fixes` returns steps with an `automatable` flag. **Key rotation is
+never automatable** — it happens in someone else's console, and this
+server has no access to it.
+
+An agent that applies the code edits and reports "fixed" while the leaked
+key is still live has made things worse: the user now believes they are
+safe. The tool descriptions say this explicitly, and every response
+repeats the count of manual steps outstanding, because the model reads
+the response far more carefully than it reads the schema.

package/dist/index.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the Qopanza API.
+ *
+ * The product thesis in one file: the person who needs this most is not
+ * going to read a security report. They are going to ask their coding
+ * agent "is my app safe to launch", and the agent needs tools that
+ * return something it can act on rather than prose it has to interpret.
+ *
+ * So every tool here returns two things — a human-readable block the
+ * agent can relay, and a structured block it can work from. The
+ * descriptions are written for a model deciding whether to call a tool,
+ * which is a different audience from a developer reading docs, and they
+ * matter more than they look: a tool the model never picks is a tool
+ * that does not exist.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const BASE_URL = (process.env.QOPANZA_BASE_URL ?? "https://api.qopanza.com/v1").replace(/\/$/, "");
+const API_KEY = process.env.QOPANZA_API_KEY ?? "";
+class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+async function call(path, body) {
+    const headers = { "Content-Type": "application/json" };
+    if (API_KEY)
+        headers["X-API-Key"] = API_KEY;
+    const response = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        let detail = response.statusText;
+        try {
+            const parsed = (await response.json());
+            if (typeof parsed.detail === "string")
+                detail = parsed.detail;
+        }
+        catch {
+            // Non-JSON error body; statusText is the best available.
+        }
+        throw new ApiError(response.status, detail);
+    }
+    return (await response.json());
+}
+const SEVERITY_ORDER = ["critical", "high", "medium", "low"];
+/**
+ * Render findings for the model to read aloud.
+ *
+ * Deliberately leads with the count and the worst item. A model
+ * summarising a long list tends to describe the first thing it read, so
+ * the first thing it reads should be the thing that matters.
+ */
+function renderScan(scan) {
+    if (!scan.reachable) {
+        return `Could not reach ${scan.target}.\n${scan.error ?? ""}`.trim();
+    }
+    const lines = [
+        `Scanned ${scan.target} — security score ${scan.score}/100`,
+        scan.summary,
+        "",
+        `Files checked: ${scan.files_scanned.length}`,
+        "",
+    ];
+    if (scan.findings.length === 0) {
+        lines.push("No problems found.");
+        return lines.join("\n");
+    }
+    const sorted = [...scan.findings].sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity));
+    for (const finding of sorted) {
+        const where = finding.line_number > 0
+            ? `${finding.location}:${finding.line_number}`
+            : finding.location;
+        const hedge = finding.confidence === "likely" ? " (needs confirming)" : "";
+        lines.push(`[${finding.severity.toUpperCase()}]${hedge} ${finding.title}`);
+        lines.push(`  where: ${where}`);
+        lines.push(`  what:  ${finding.explanation}`);
+        lines.push(`  fix:   ${finding.remediation}`);
+        lines.push("");
+    }
+    lines.push(scan.fix_hint);
+    return lines.join("\n");
+}
+const TOOLS = [
+    {
+        name: "scan_app_url",
+        description: "Scan a deployed website for exposed API keys, database credentials and " +
+            "missing security headers, given only its URL. Reads the JavaScript the " +
+            "site actually serves, so anything found is ALREADY PUBLIC to every " +
+            "visitor. Use this when the user asks whether their app is safe, secure, " +
+            "or ready to launch, or mentions deploying. Works on Lovable, Bolt, v0, " +
+            "Replit, Vercel and Netlify apps. Free on every plan.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "The site's address. A bare domain like myapp.lovable.app is fine.",
+                },
+            },
+            required: ["url"],
+        },
+    },
+    {
+        name: "scan_app_code",
+        description: "Scan one file's contents for hardcoded secrets (OpenAI, Stripe, AWS, " +
+            "Supabase service keys) and database queries that let any visitor read " +
+            "other people's rows. Use this while editing a file, or on files you just " +
+            "wrote, before the user deploys. Free.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: {
+                    type: "string",
+                    description: "Path of the file, used to judge whether it ships to the browser.",
+                },
+                content: { type: "string", description: "The file's contents." },
+            },
+            required: ["filename", "content"],
+        },
+    },
+    {
+        name: "get_fixes",
+        description: "Get the exact changes that fix findings from a scan: code edits with " +
+            "before/after, config files to create, SQL policies, and the console steps " +
+            "a human must do. Pass the findings array from scan_app_url or " +
+            "scan_app_code. Requires a paid plan (App Security or above); returns a " +
+            "clear message explaining how to upgrade if the account is on Free.\n\n" +
+            "IMPORTANT: steps have an `automatable` flag. Steps where it is false — " +
+            "rotating a leaked key in the provider's dashboard, enabling RLS in " +
+            "Supabase — CANNOT be done for the user. Never tell the user the problem " +
+            "is fixed while any of those remain: a key removed from the code but not " +
+            "rotated is still live and still public. Apply the automatable edits, then " +
+            "list the manual steps and say plainly that they are outstanding.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                findings: {
+                    type: "array",
+                    description: "The findings array returned by a scan tool, verbatim.",
+                    items: { type: "object" },
+                },
+                host: {
+                    type: "string",
+                    // Optional on purpose, and deliberately *not* a two-value enum.
+                    // An agent handed a choice between Vercel and Netlify will pick
+                    // one — that is what agents do — and the API would then return
+                    // a `vercel.json` for a Render site. Omitting this returns the
+                    // header values plus instructions that work anywhere, which is
+                    // the correct answer when nobody actually knows.
+                    enum: [
+                        "vercel",
+                        "netlify",
+                        "cloudflare_pages",
+                        "firebase",
+                        "render",
+                        "fly",
+                        "github_pages",
+                        "cloudfront",
+                        "s3",
+                        "digitalocean",
+                        "nginx",
+                        "other",
+                    ],
+                    description: "Where the app is deployed. OMIT THIS unless you actually know — " +
+                        "scan_app_url returns `detected_host`, read off the site's own " +
+                        "response headers; pass that value through if it is present. Do " +
+                        "not guess: a config file for the wrong platform is inert, and " +
+                        "the user will redeploy believing they are fixed. Omitted means " +
+                        "'unknown', which returns portable instructions instead.",
+                },
+            },
+            required: ["findings"],
+        },
+    },
+    {
+        name: "scan_crypto",
+        description: "Scan code for quantum-vulnerable cryptography (RSA, ECDSA, ECDH, MD5, " +
+            "SHA-1) and report a quantum risk score. Use this when the user asks about " +
+            "quantum safety, post-quantum readiness, or crypto compliance. Note: most " +
+            "apps built on Lovable/Bolt/v0 have no cryptography of their own, so an " +
+            "empty result here is normal and not a problem — prefer scan_app_url for " +
+            "'is my app secure'. Free.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                filename: { type: "string" },
+                content: { type: "string" },
+            },
+            required: ["filename", "content"],
+        },
+    },
+];
+const server = new Server({ name: "qopanza", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        switch (name) {
+            case "scan_app_url": {
+                const scan = await call("/app-scan/url", { url: args.url });
+                return {
+                    content: [{ type: "text", text: renderScan(scan) }],
+                    structuredContent: scan,
+                };
+            }
+            case "scan_app_code": {
+                const scan = await call("/app-scan/code", {
+                    filename: args.filename,
+                    content: args.content,
+                });
+                return {
+                    content: [{ type: "text", text: renderScan(scan) }],
+                    structuredContent: scan,
+                };
+            }
+            case "get_fixes": {
+                const plan = await call("/app-scan/fix", { findings: args.findings, host: args.host ?? null });
+                const lines = [
+                    `${plan.total} fix${plan.total === 1 ? "" : "es"} generated.`,
+                    "",
+                ];
+                for (const remediation of plan.remediations) {
+                    lines.push(`## ${remediation.title}`);
+                    lines.push(remediation.summary);
+                    lines.push(`Risk if ignored: ${remediation.risk_if_ignored}`);
+                    for (const step of remediation.steps) {
+                        const tag = step.automatable ? "[you can do this]" : "[USER MUST DO THIS]";
+                        lines.push(`  ${step.order}. ${tag} ${step.title}`);
+                        lines.push(`     ${step.detail}`);
+                        if (step.file)
+                            lines.push(`     file: ${step.file}:${step.line ?? ""}`);
+                        if (step.create_file)
+                            lines.push(`     create: ${step.create_file}`);
+                        if (step.console_url)
+                            lines.push(`     go to: ${step.console_url}`);
+                    }
+                    lines.push("");
+                }
+                // Repeated at the end because a model summarising a long response
+                // weights the last thing it read, and this is the sentence that
+                // stops it reporting a half-done fix as finished.
+                lines.push(`${plan.manual_steps_required} step(s) require the user and cannot be ` +
+                    `automated. The problem is NOT fixed until those are done — in ` +
+                    `particular, a leaked key that has not been rotated is still live.`);
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    structuredContent: plan,
+                };
+            }
+            case "scan_crypto": {
+                const scan = await call("/scan/code", {
+                    filename: args.filename,
+                    content: args.content,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(scan, null, 2) }],
+                    structuredContent: scan,
+                };
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        // 402 is the interesting one: it is not a failure, it is a price. The
+        // model should relay it as an option rather than as an error the user
+        // needs to debug, so it is phrased that way here.
+        if (error instanceof ApiError && error.status === 402) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `This needs a paid plan.\n\n${error.message}\n\n` +
+                            `The scan results you already have are complete — nothing was ` +
+                            `hidden. You can fix the problems by hand from the descriptions, ` +
+                            `or upgrade to have the exact changes generated.`,
+                    },
+                ],
+            };
+        }
+        if (error instanceof ApiError && error.status === 401) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No valid API key. Set QOPANZA_API_KEY in this MCP server's " +
+                            "environment. A free key takes about a minute to create.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Scan failed: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    // stdio, so the agent launches this as a subprocess. Nothing may be
+    // written to stdout except protocol frames — a stray console.log
+    // corrupts the stream and the server appears to hang.
+    await server.connect(new StdioServerTransport());
+    console.error(`Qopanza MCP server ready (api: ${BASE_URL})`);
+}
+main().catch((error) => {
+    console.error("Fatal:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "qopanza-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AI coding agents: scan an app for exposed secrets and open databases, then fix them",
+  "license": "Apache-2.0",
+  "author": "Gsente LLC",
+  "type": "module",
+  "bin": { "qopanza-mcp": "dist/index.js" },
+  "files": ["dist/index.js", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3"
+  },
+  "engines": { "node": ">=18" },
+  "homepage": "https://qopanza.com/docs#mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isingomajoel2023/qopanza-sdks.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/isingomajoel2023/qopanza-sdks/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "security",
+    "secrets",
+    "supabase",
+    "post-quantum",
+    "qopanza"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}