@thenavidm/slipway 0.1.0

package/dist/schema.js

@@ -0,0 +1,192 @@
+/**
+ * One schema interface for every tool, whatever wrote it.
+ *
+ * A hand-written tool uses Zod. A tool generated from an API contract uses the
+ * contract's JSON Schema. Both become a Standard Schema object here, which is
+ * what the MCP SDK validates and advertises, and what the CLI derives its
+ * flags from. Because both surfaces read the same object, an argument one
+ * accepts the other accepts too.
+ */
+import { fromJsonSchema } from "@modelcontextprotocol/server";
+const TARGET = { target: "draft-2020-12" };
+/**
+ * Wrap a raw JSON Schema so it validates and converts like a Zod schema.
+ *
+ * This is how a tool generated from an OpenAPI document or a pinned contract
+ * joins the same tool list as hand-written ones.
+ */
+export function jsonSchema(schema) {
+    return fromJsonSchema(schema);
+}
+/** The input of a tool that takes nothing. */
+export function emptyInput() {
+    return jsonSchema({ type: "object", properties: {}, additionalProperties: false });
+}
+export function isSchema(value) {
+    const std = value?.["~standard"];
+    return typeof std?.validate === "function" && typeof std.jsonSchema?.input === "function";
+}
+/** The JSON Schema an MCP client receives for this input. */
+export function inputJsonSchema(schema) {
+    return schema["~standard"].jsonSchema.input(TARGET);
+}
+export function outputJsonSchema(schema) {
+    return schema["~standard"].jsonSchema.output(TARGET);
+}
+/** Validate with the schema's own validator, sync or async, and flatten the issues. */
+export async function validate(schema, value) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues) {
+        return {
+            ok: false,
+            issues: result.issues.map((issue) => ({
+                path: (issue.path ?? [])
+                    .map((part) => (typeof part === "object" && part !== null && "key" in part ? String(part.key) : String(part)))
+                    .join("."),
+                message: plainMessage(issue.message),
+            })),
+        };
+    }
+    return { ok: true, value: result.value };
+}
+/**
+ * A JSON Schema validator names fields as `data/a/b`. A person typing flags,
+ * and a model reading the error, both know the field as `a.b`.
+ */
+function plainMessage(message) {
+    return message
+        .replace(/\bdata\/([A-Za-z0-9_.\-/]+)/g, (_match, path) => path.replace(/\//g, "."))
+        .replace(/\bdata (must|should)\b/g, "input $1");
+}
+export function formatIssues(issues) {
+    return issues.map((issue) => (issue.path ? `${issue.path}: ${issue.message}` : issue.message)).join("; ");
+}
+/** The names Slipway adds, which a tool's own input may not use. */
+export const CONTROL_NAMES = ["confirm", "wait_seconds"];
+/**
+ * Short on purpose: it is repeated in every confirmed tool a client lists.
+ * What the effect is lives in the tool's own description and annotations.
+ */
+export const CONFIRM_DESCRIPTION = "Set true only when the user asked for exactly this action.";
+/** The schema already carries the range and the default, so the words only say what the number is for. */
+export const WAIT_DESCRIPTION = "Seconds to wait for the job to finish before returning it to check later.";
+/**
+ * A schema as clients receive it, without the `$schema` line that names its
+ * dialect. A client reads JSON Schema 2020-12 when no dialect is named, so
+ * the line only adds bytes to every tool in every listing.
+ */
+export function advertised(schema) {
+    const std = schema["~standard"];
+    const plain = (json) => {
+        if (!("$schema" in json))
+            return json;
+        const { $schema: _dialect, ...rest } = json;
+        return rest;
+    };
+    return {
+        "~standard": {
+            version: std.version,
+            vendor: std.vendor,
+            validate: (value) => std.validate(value),
+            ...(std.types ? { types: std.types } : {}),
+            jsonSchema: {
+                input: (options) => plain(std.jsonSchema.input(options)),
+                output: (options) => plain(std.jsonSchema.output(options)),
+            },
+        },
+    };
+}
+/**
+ * Add Slipway's own arguments to any schema: `confirm` for a tool that needs
+ * confirming, `wait_seconds` for a job.
+ *
+ * Validation takes them out before the author's schema sees the rest and puts
+ * them back afterwards, so a strict contract schema with
+ * `additionalProperties: false` still accepts them, and the author never
+ * declares them by hand.
+ */
+export function withControls(schema, controls) {
+    if (!controls.confirm && !controls.wait)
+        return schema;
+    const std = schema["~standard"];
+    const wait = controls.wait;
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "slipway",
+            validate: (value) => {
+                const record = value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+                if (!record)
+                    return std.validate(value);
+                const { confirm, wait_seconds: waitSeconds, ...rest } = record;
+                const issues = [];
+                if (controls.confirm && confirm !== undefined && typeof confirm !== "boolean")
+                    issues.push({ message: "Expected true or false", path: ["confirm"] });
+                if (wait && waitSeconds !== undefined && (typeof waitSeconds !== "number" || !Number.isInteger(waitSeconds) || waitSeconds < 0 || waitSeconds > wait.maxSeconds)) {
+                    issues.push({ message: `Expected a whole number of seconds from 0 to ${wait.maxSeconds}`, path: ["wait_seconds"] });
+                }
+                if (issues.length)
+                    return { issues };
+                // A control this tool does not take stays in the input, for the author's schema to judge.
+                const passOn = { ...rest, ...(!controls.confirm && confirm !== undefined ? { confirm } : {}), ...(!wait && waitSeconds !== undefined ? { wait_seconds: waitSeconds } : {}) };
+                const finish = (result) => result.issues
+                    ? result
+                    : {
+                        value: {
+                            ...result.value,
+                            ...(controls.confirm && confirm !== undefined ? { confirm } : {}),
+                            ...(wait && waitSeconds !== undefined ? { wait_seconds: waitSeconds } : {}),
+                        },
+                    };
+                const result = std.validate(passOn);
+                return (result instanceof Promise ? result.then(finish) : finish(result));
+            },
+            jsonSchema: {
+                input: (options) => {
+                    const base = std.jsonSchema.input(options);
+                    const properties = { ...(base.properties ?? {}) };
+                    if (controls.confirm)
+                        properties.confirm = { type: "boolean", description: CONFIRM_DESCRIPTION };
+                    if (wait) {
+                        properties.wait_seconds = { type: "integer", minimum: 0, maximum: wait.maxSeconds, default: wait.defaultSeconds, description: WAIT_DESCRIPTION };
+                    }
+                    return { ...base, properties };
+                },
+                output: (options) => std.jsonSchema.output(options),
+            },
+        },
+    };
+}
+/** Serialized size of a schema, the number that decides what a client pays to load the tool. */
+export function schemaBytes(schema) {
+    return Buffer.byteLength(JSON.stringify(schema));
+}
+/**
+ * Find `$defs` blocks that repeat inside one schema.
+ *
+ * A generator that inlines a referenced body and also keeps it under `$defs`
+ * ships the same definitions twice; a schema of a few hundred kilobytes is
+ * often half repetition.
+ */
+export function repeatedDefinitions(schema) {
+    const seen = new Map();
+    const visit = (node) => {
+        if (node === null || typeof node !== "object")
+            return;
+        if (Array.isArray(node))
+            return node.forEach(visit);
+        const record = node;
+        for (const key of ["$defs", "definitions"]) {
+            const defs = record[key];
+            if (defs && typeof defs === "object") {
+                for (const [name, value] of Object.entries(defs)) {
+                    const fingerprint = `${name}:${JSON.stringify(value).length}`;
+                    seen.set(fingerprint, (seen.get(fingerprint) ?? 0) + 1);
+                }
+            }
+        }
+        Object.values(record).forEach(visit);
+    };
+    visit(schema);
+    return [...seen.entries()].filter(([, count]) => count > 1).map(([fingerprint]) => fingerprint.split(":")[0]);
+}

package/dist/search.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Finding the tool for a task by what it does, not by its name.
+ *
+ * A server with a hundred tools is only usable when the right one can be found
+ * from the words someone would use to ask for it. The same ranking answers
+ * `which` in a terminal and `search_tools` for a model.
+ */
+import type { Tool } from "./tool.js";
+export type Match = {
+    tool: Tool;
+    score: number;
+};
+export declare function searchTools(tools: readonly Tool[], query: string, limit?: number): Match[];
+/** Edit distance, for "did you mean" on a mistyped command. */
+export declare function distance(a: string, b: string): number;
+export declare function didYouMean(input: string, candidates: readonly string[]): string | undefined;
+/** The first sentence of a description, for one-line listings. */
+export declare function firstSentence(text: string, max?: number): string;

package/dist/search.js

@@ -0,0 +1,119 @@
+/**
+ * Finding the tool for a task by what it does, not by its name.
+ *
+ * A server with a hundred tools is only usable when the right one can be found
+ * from the words someone would use to ask for it. The same ranking answers
+ * `which` in a terminal and `search_tools` for a model.
+ */
+function words(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 1)
+        .map(stem);
+}
+/** Close enough for matching "posts" to "post" and "scheduling" to "schedul". */
+function stem(word) {
+    if (word.length > 4 && word.endsWith("ies"))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 5 && word.endsWith("ing"))
+        return word.slice(0, -3);
+    if (word.length > 4 && word.endsWith("es"))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith("s"))
+        return word.slice(0, -1);
+    return word;
+}
+/**
+ * Words people use for the same action. Tool names settle on one verb, and the
+ * person searching rarely picks the same one: they "remove" what the API calls
+ * "delete".
+ */
+const SYNONYMS = [
+    ["delete", "remove", "erase", "trash", "destroy", "drop", "unpublish"],
+    ["create", "add", "new", "make", "insert", "write"],
+    ["update", "edit", "change", "modify", "rename", "set"],
+    ["list", "show", "browse", "all", "index", "enumerate"],
+    ["get", "read", "fetch", "view", "lookup", "retrieve", "open"],
+    ["search", "find", "query", "lookup", "filter"],
+    ["send", "email", "message", "notify", "deliver"],
+    ["post", "publish", "share", "tweet", "status"],
+    ["schedule", "queue", "plan", "later"],
+    ["upload", "attach", "import"],
+    ["download", "export", "save", "backup"],
+    ["stat", "analytic", "metric", "insight", "report", "count"],
+    ["user", "member", "account", "person", "contact", "customer", "student", "subscriber"],
+].map((group) => group.map(stem));
+const RELATED = new Map();
+for (const group of SYNONYMS)
+    for (const word of group)
+        RELATED.set(word, [...new Set([...(RELATED.get(word) ?? []), ...group])]);
+function hits(query, haystack) {
+    const direct = exact(query, haystack);
+    if (direct > 0)
+        return direct;
+    // A synonym counts for a little less than the word itself, so an exact match still wins.
+    return (RELATED.get(query) ?? []).some((word) => word !== query && exact(word, haystack) === 1) ? 0.75 : 0;
+}
+function exact(query, haystack) {
+    if (haystack.includes(query))
+        return 1;
+    return haystack.some((word) => word.startsWith(query) || query.startsWith(word)) ? 0.5 : 0;
+}
+export function searchTools(tools, query, limit = 10) {
+    const terms = [...new Set(words(query))];
+    if (terms.length === 0)
+        return [];
+    const phrase = query.trim().toLowerCase();
+    const scored = tools.map((tool) => {
+        const name = words(tool.name);
+        const title = words(tool.title);
+        const tags = tool.tags.flatMap(words);
+        const description = words(tool.description);
+        let score = 0;
+        let matched = 0;
+        for (const term of terms) {
+            const got = hits(term, name) * 5 + hits(term, title) * 4 + hits(term, tags) * 3 + hits(term, description);
+            if (got > 0)
+                matched++;
+            score += got;
+        }
+        // A tool that matches every word beats one that matches one word strongly.
+        score *= matched / terms.length;
+        if (phrase.length > 3 && (tool.title.toLowerCase().includes(phrase) || tool.description.toLowerCase().includes(phrase)))
+            score += 3;
+        return { tool, score };
+    });
+    return scored
+        .filter((match) => match.score > 0)
+        .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+        .slice(0, limit);
+}
+/** Edit distance, for "did you mean" on a mistyped command. */
+export function distance(a, b) {
+    const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        rows[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+        }
+    }
+    return rows[a.length][b.length];
+}
+export function didYouMean(input, candidates) {
+    const target = input.toLowerCase();
+    let best;
+    for (const candidate of candidates) {
+        const score = candidate.startsWith(target) ? 0 : distance(target, candidate);
+        if (score <= Math.max(2, Math.floor(target.length / 4)) && (!best || score < best.score))
+            best = { candidate, score };
+    }
+    return best?.candidate;
+}
+/** The first sentence of a description, for one-line listings. */
+export function firstSentence(text, max = 100) {
+    const first = text.trim().split(/(?<=[.!?])\s/)[0] ?? "";
+    return first.length > max ? `${first.slice(0, max - 1).trimEnd()}…` : first;
+}

package/dist/serve.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Serving an app over stdio, which every local client launches, or HTTP.
+ */
+import { type App } from "./app.js";
+/**
+ * Serve over stdio.
+ *
+ * The setup check runs after the server is already answering. A client gives a
+ * server a few seconds to start, and a server that waits on a slow check, or
+ * exits because nothing is configured yet, shows up as broken instead of as a
+ * set of tools that explain what to configure.
+ */
+export declare function serveStdioApp(app: App, env: NodeJS.ProcessEnv): Promise<void>;
+export type HttpOptions = {
+    host: string;
+    port: number;
+    token?: string;
+};
+export declare function httpOptions(app: App, env: NodeJS.ProcessEnv, argv: string[]): HttpOptions;
+/**
+ * Serve over Streamable HTTP, for a machine that is always on.
+ *
+ * Bound to 127.0.0.1 by default. The server acts with whatever account it was
+ * given, so it refuses to listen anywhere else without a bearer token rather
+ * than trusting that nobody will find the port.
+ */
+export declare function serveHttpApp(app: App, env: NodeJS.ProcessEnv, options: HttpOptions): Promise<{
+    close: () => Promise<void>;
+    url: string;
+}>;

package/dist/serve.js

@@ -0,0 +1,149 @@
+/**
+ * Serving an app over stdio, which every local client launches, or HTTP.
+ */
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { stderrLogger } from "./app.js";
+import { UsageError } from "./errors.js";
+/**
+ * Serve over stdio.
+ *
+ * The setup check runs after the server is already answering. A client gives a
+ * server a few seconds to start, and a server that waits on a slow check, or
+ * exits because nothing is configured yet, shows up as broken instead of as a
+ * set of tools that explain what to configure.
+ */
+export async function serveStdioApp(app, env) {
+    const log = stderrLogger(app.envPrefix, env);
+    const handle = serveStdio(() => app.createServer(env));
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void handle.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    void warnIfUnconfigured(app, env, log.warn);
+}
+async function warnIfUnconfigured(app, env, warn) {
+    try {
+        const ctx = await app.context(env);
+        if (app.definition.configured && !(await app.definition.configured(ctx))) {
+            warn(`Nothing is configured yet. Tools that need an account will say what is missing. Run \`${app.bins.cli} doctor\`.`);
+        }
+    }
+    catch (error) {
+        warn(`Setup is incomplete: ${error.message} Run \`${app.bins.cli} doctor\`.`);
+    }
+}
+export function httpOptions(app, env, argv) {
+    const at = argv.findIndex((token) => token === "--port" || token.startsWith("--port="));
+    const raw = at === -1 ? env[`${app.envPrefix}_HTTP_PORT`] : argv[at].includes("=") ? argv[at].split("=")[1] : argv[at + 1];
+    const port = Number(raw ?? 8787);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new UsageError(`--port expects a port number, got '${raw}'.`);
+    return {
+        host: env[`${app.envPrefix}_HTTP_HOST`]?.trim() || "127.0.0.1",
+        port,
+        token: env[`${app.envPrefix}_HTTP_TOKEN`]?.trim() || undefined,
+    };
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/**
+ * Serve over Streamable HTTP, for a machine that is always on.
+ *
+ * Bound to 127.0.0.1 by default. The server acts with whatever account it was
+ * given, so it refuses to listen anywhere else without a bearer token rather
+ * than trusting that nobody will find the port.
+ */
+export async function serveHttpApp(app, env, options) {
+    const loopback = LOOPBACK.has(options.host);
+    if (!loopback && !options.token) {
+        throw new UsageError(`Refusing to listen on ${options.host} without ${app.envPrefix}_HTTP_TOKEN. Anyone who can reach the port would act as your account.`);
+    }
+    const log = stderrLogger(app.envPrefix, env);
+    const handler = createMcpHandler(() => app.createServer(env));
+    const server = createServer((req, res) => {
+        void handle(app, handler.fetch, options, loopback, req, res).catch((error) => {
+            if (!res.headersSent)
+                res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: error?.message ?? "internal error" }, id: null }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => resolve());
+    });
+    // Port 0 asks the system for a free port, so the real one is read back after listening.
+    const address = server.address();
+    const port = address && typeof address === "object" ? address.port : options.port;
+    const url = `http://${options.host.includes(":") && !options.host.startsWith("[") ? `[${options.host}]` : options.host}:${port}/mcp`;
+    log.info(`listening on ${url}${options.token ? " (bearer token required)" : ""}`);
+    return {
+        url,
+        close: async () => {
+            await handler.close();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+async function handle(app, fetchMcp, options, loopback, req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    // A page in a browser can make requests to localhost. Checking the Host header
+    // stops a site that resolves its own name to 127.0.0.1 from reaching this server.
+    if (loopback && !LOOPBACK.has(url.hostname)) {
+        res.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: "forbidden host" }));
+        return;
+    }
+    if (url.pathname === "/health") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: true, name: app.name, version: app.version, tools: app.tools().length }));
+        return;
+    }
+    if (url.pathname !== "/mcp") {
+        res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "not found" }));
+        return;
+    }
+    if (options.token && req.headers.authorization !== `Bearer ${options.token}`) {
+        res.writeHead(401, { "content-type": "application/json", "www-authenticate": "Bearer" }).end(JSON.stringify({ error: "unauthorized" }));
+        return;
+    }
+    const controller = new AbortController();
+    res.on("close", () => controller.abort());
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value))
+            for (const item of value)
+                headers.append(key, item);
+        else if (value !== undefined)
+            headers.set(key, value);
+    }
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const request = new Request(url, {
+        method: req.method,
+        headers,
+        body: hasBody ? Readable.toWeb(req) : undefined,
+        signal: controller.signal,
+        duplex: "half",
+    });
+    const response = await fetchMcp(request);
+    const out = {};
+    response.headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    res.writeHead(response.status, out);
+    if (response.body) {
+        const reader = response.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            res.write(value);
+        }
+    }
+    res.end();
+}

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The MCP surface.
+ *
+ * Every tool is registered from its definition with the annotations its risk
+ * implies, so a client that auto-approves reads or prompts on writes gets an
+ * honest answer from every tool, not only the ones someone remembered to mark.
+ */
+import { McpServer, type ToolAnnotations } from "@modelcontextprotocol/server";
+import type { App } from "./app.js";
+import type { Policy } from "./policy.js";
+import type { Tool } from "./tool.js";
+/** Claude Code shows a person a permission prompt on every call to a tool carrying this, in any mode. */
+export declare const REQUIRES_USER_INTERACTION = "anthropic/requiresUserInteraction";
+/** Claude Code raises its result-size limit for a tool carrying this. */
+export declare const MAX_RESULT_SIZE_CHARS = "anthropic/maxResultSizeChars";
+export declare function annotationsFor(tool: Tool): ToolAnnotations;
+export declare function metaFor(tool: Tool, policy: Policy): Record<string, unknown> | undefined;
+/** The `_meta` key that marks a result served from the local cache, with its age. */
+export declare const CACHE_META = "slipway/cache";
+export declare function buildServer<Ctx>(app: App<Ctx>, env: NodeJS.ProcessEnv): McpServer;