gasp-standard-mcp 1.18.0 → 1.19.0

package/README.md

@@ -29,6 +29,16 @@ Add to your project `.mcp.json` or `~/.claude/settings.json`:
 
 Restart your MCP client after adding the config.
 
+### Hosted endpoint
+
+The same server runs over Streamable HTTP for clients that connect to a remote server, such as the Claude connectors directory. Every tool is read-only and the standard is public, so the endpoint takes no authentication.
+
+```bash
+npx gasp-standard-mcp-http          # PORT=3000, endpoint /mcp, /health for the version and tool count
+```
+
+`PORT`, `HOST` and `MCP_PATH` set where it listens. `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` (comma-separated) refuse requests whose Host or Origin header is not listed, the DNS-rebinding guard for a server reachable from a browser; set `MCP_ALLOWED_HOSTS` to the public hostname in production. The `Dockerfile` in this directory serves the published package the same way. Every tool carries a `title` and `readOnlyHint: true`, so a client can run them without a per-call prompt. The HTTP server writes one JSON line to stderr per tool call (the tool, the duration, success or error and the client's name and version; never the arguments or the result), so the host's logs count calls per tool.
+
 ## Tools
 
 | Tool | Description |
@@ -59,7 +69,7 @@ The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return pat
 
 ## Data
 
-Version 1.18.0.
+Version 1.19.0.
 
 - 306 metrics across 13 departments
 - 94 glossary definitions (81 SaaS domain + 13 GASP framework)
@@ -89,7 +99,7 @@ Version 1.18.0.
 - The drift scorer (`src/ossie/drift.ts`, behind `score_drift`) runs a company's metrics and the canonical ones side by side on the synthetic SaaS dataset (`src/synthetic.ts`, also the test fixture) in PGlite, loaded on first use from the optional dependency `@electric-sql/pglite`; without it the tool says so and runs nothing
 - The metric compiler (`src/ossie/company.ts`, behind `compile_model`) writes every covered GASP metric into a company's own Ossie model, direct or staged, over their datasets, sources and field expressions. The test suite compiles the fixture adapter and checks every direct and staged value against the reference export on the fixture rows
 - Adapter schema 1.1 (`standard/gasp-adapter-schema.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-adapter-v1.json): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. The schema travels in the bundled data as `adapterSchema` and `validate_adapter` applies it with Ajv, so validation works offline. `npm run derive` writes a ready template to `standard/exports/gasp-adapter-template.json` (served at https://gaspwiki.com/downloads/gasp-adapter-template.json) and the tests validate it against the schema
-- GASP Ossie extension schema 1 (`standard/gasp-ossie-extension-v1.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-ossie-extension-v1.json): the parsed `data` of every `custom_extensions` entry GASP writes under `vendor_name: GASP`, one definition per placement (model, dataset, metric, mapping), strict so each key GASP adds outside Ossie is listed. It travels in the bundled data as `extensionSchema` and the cross-document checks (`checkExport` in `src/ossie/check.ts`) validate every GASP payload against it in the export, `validate_mapping`, `compile_model`, `propose_mapping` and `record_decision`
+- GASP Ossie extension schema 1 (`standard/gasp-ossie-extension-v1.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-ossie-extension-v1.json): the parsed `data` of every `custom_extensions` entry GASP writes under `vendor_name: GASP`, one definition per placement (model, dataset, metric, mapping), strict so each key GASP adds outside Ossie is listed. It travels in the bundled data as `extensionSchema` and the cross-document checks (`checkExport` in `src/ossie/check.ts`) validate every GASP payload against it in the export, `validate_mapping`, `compile_model`, `propose_mapping` and `record_decision`. Every tool reads `data` as the JSON string the pinned Ossie schema defines or as an object (the form apache/ossie #522 proposes), under `custom_extensions` or the `nonportable_extensions` key the same proposal renames it to, and writes the pinned form under the pinned key
 - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
 
 ## Examples

package/build/http.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * The GASP Standard MCP server over Streamable HTTP, for a hosted endpoint
+ * such as https://mcp.gaspwiki.com/mcp that Claude connects to as a remote
+ * server. Stateless: every request gets its own transport and server over the
+ * data loaded once, so any number of instances can sit behind one hostname.
+ * No authentication: the standard is public and every tool is read-only.
+ *
+ * Run `gasp-standard-mcp-http` (or `node build/http.js`). Environment:
+ * `PORT` (default 3000), `HOST` (default 0.0.0.0), `MCP_PATH` (default /mcp),
+ * `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` (comma-separated; when either
+ * is set, requests whose Host or Origin header is not listed are refused, the
+ * DNS-rebinding guard for a server reachable from a browser).
+ *
+ * Every tool call is written to stderr as one JSON line, `{"event":"tool",
+ * "tool":"lookup_metric","ms":12,"ok":true,"client":"claude-ai/1.0"}`, so the
+ * host's log stream counts calls per tool. Arguments and results are never
+ * logged, which is what the privacy policy at gaspwiki.com/privacy promises.
+ */
+import { type Server } from "node:http";
+export interface HttpOptions {
+    port?: number;
+    host?: string;
+    /** The path the MCP endpoint answers on; everything else is the health page or 404. */
+    path?: string;
+    allowedHosts?: string[];
+    allowedOrigins?: string[];
+}
+/** The listening server. `port: 0` picks a free port (tests). */
+export declare function startHttpServer(options?: HttpOptions): Server;

package/build/http.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * The GASP Standard MCP server over Streamable HTTP, for a hosted endpoint
+ * such as https://mcp.gaspwiki.com/mcp that Claude connects to as a remote
+ * server. Stateless: every request gets its own transport and server over the
+ * data loaded once, so any number of instances can sit behind one hostname.
+ * No authentication: the standard is public and every tool is read-only.
+ *
+ * Run `gasp-standard-mcp-http` (or `node build/http.js`). Environment:
+ * `PORT` (default 3000), `HOST` (default 0.0.0.0), `MCP_PATH` (default /mcp),
+ * `MCP_ALLOWED_HOSTS` and `MCP_ALLOWED_ORIGINS` (comma-separated; when either
+ * is set, requests whose Host or Origin header is not listed are refused, the
+ * DNS-rebinding guard for a server reachable from a browser).
+ *
+ * Every tool call is written to stderr as one JSON line, `{"event":"tool",
+ * "tool":"lookup_metric","ms":12,"ok":true,"client":"claude-ai/1.0"}`, so the
+ * host's log stream counts calls per tool. Arguments and results are never
+ * logged, which is what the privacy policy at gaspwiki.com/privacy promises.
+ */
+import { createServer as createHttp } from "node:http";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { PKG_VERSION, TOOL_COUNT, createServer } from "./server.js";
+const CORS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version",
+    "Access-Control-Expose-Headers": "Mcp-Session-Id, Mcp-Protocol-Version",
+};
+/** The listening server. `port: 0` picks a free port (tests). */
+export function startHttpServer(options = {}) {
+    const path = options.path ?? "/mcp";
+    const guard = options.allowedHosts?.length || options.allowedOrigins?.length
+        ? { enableDnsRebindingProtection: true, allowedHosts: options.allowedHosts, allowedOrigins: options.allowedOrigins }
+        : {};
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, CORS);
+            res.end();
+            return;
+        }
+        if (url.pathname === path) {
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true, ...guard });
+            const server = createServer({ onToolCall: (r) => console.error(JSON.stringify(r)) });
+            res.on("close", () => { void transport.close(); void server.close(); });
+            for (const [k, v] of Object.entries(CORS))
+                res.setHeader(k, v);
+            await server.connect(transport);
+            await transport.handleRequest(req, res);
+            return;
+        }
+        if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/health")) {
+            res.writeHead(200, { "Content-Type": "application/json", ...CORS });
+            res.end(JSON.stringify({ name: "gasp-standard", version: PKG_VERSION, tools: TOOL_COUNT, endpoint: path, documentation: "https://gaspwiki.com/v1/tools" }));
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end(`Not found. The MCP endpoint is ${path}.`);
+    };
+    const server = createHttp((req, res) => {
+        handle(req, res).catch((err) => {
+            console.error("[gasp-standard-mcp-http]", err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+            }
+            if (!res.writableEnded)
+                res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null }));
+        });
+    });
+    server.listen(options.port ?? 3000, options.host ?? "0.0.0.0");
+    return server;
+}
+const list = (v) => v?.split(",").map((s) => s.trim()).filter(Boolean);
+const invokedDirectly = (() => {
+    try {
+        return process.argv[1] !== undefined && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    const port = Number(process.env.PORT ?? 3000);
+    const path = process.env.MCP_PATH ?? "/mcp";
+    const server = startHttpServer({ port, host: process.env.HOST, path, allowedHosts: list(process.env.MCP_ALLOWED_HOSTS), allowedOrigins: list(process.env.MCP_ALLOWED_ORIGINS) });
+    server.on("listening", () => console.error(`[gasp-standard-mcp-http] ${PKG_VERSION}: ${TOOL_COUNT} tools on port ${port}${path}`));
+    const stop = () => server.close(() => process.exit(0));
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+}