toolroll 0.5.0

package/dist/mcp-connect.js

@@ -0,0 +1,252 @@
+/**
+ * One-click connections: services whose MCP servers let an app register
+ * itself (OAuth dynamic client registration, with PKCE), so connecting one is
+ * a sign-in and nothing else: no developer app to create, no key to paste.
+ *
+ * Connect finds the server's sign-in (its protected-resource metadata, or the
+ * authorization server at its origin), registers Toolroll as a client
+ * with this console's callback, and sends the person to the service to sign
+ * in. The callback trades the code for tokens, which live in the tool's own
+ * secrets file (never the database, never a log), and the tool joins the
+ * project like any other: tested, listed, and given to teammates under rules.
+ * The worker refreshes tokens before they expire.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { addToolTo, projectToolsOf, readToolSecrets, setToolSecrets, testToolOf } from "./project-tools.js";
+import { envValue } from "./names.js";
+/** Services verified to connect this way (their servers speak streamable HTTP and register clients on the spot). */
+export const ONE_CLICK = [
+    { id: "stripe", label: "Stripe", url: "https://mcp.stripe.com/", about: "Payments, customers, refunds and invoices." },
+    { id: "notion", label: "Notion", url: "https://mcp.notion.com/mcp", about: "Pages and databases: search, read and write." },
+    { id: "linear", label: "Linear", url: "https://mcp.linear.app/mcp", about: "Issues, projects and comments." },
+    { id: "sentry", label: "Sentry", url: "https://mcp.sentry.dev/mcp", about: "Errors and issues, with their stack traces." },
+    { id: "atlassian", label: "Jira and Confluence", url: "https://mcp.atlassian.com/v1/mcp", about: "Jira issues and Confluence pages." },
+    { id: "intercom", label: "Intercom", url: "https://mcp.intercom.com/mcp", about: "Customer conversations and contacts." },
+    { id: "attio", label: "Attio", url: "https://mcp.attio.com/mcp", about: "Your CRM: people, companies, deals and notes." },
+    { id: "zapier", label: "Zapier", url: "https://mcp.zapier.com/api/mcp/mcp", about: "Thousands of apps, through the actions you choose in Zapier." },
+    { id: "square", label: "Square", url: "https://mcp.squareup.com/mcp", about: "Payments, orders, customers and catalog." },
+    { id: "paypal", label: "PayPal", url: "https://mcp.paypal.com/mcp", about: "Payments, invoices and disputes." },
+    { id: "klaviyo", label: "Klaviyo", url: "https://mcp.klaviyo.com/mcp", about: "Email and SMS lists, campaigns and profiles." },
+    { id: "webflow", label: "Webflow", url: "https://mcp.webflow.com/mcp", about: "Sites, pages and CMS items." },
+    { id: "wix", label: "Wix", url: "https://mcp.wix.com/mcp", about: "Your Wix site, store and bookings." },
+    { id: "canva", label: "Canva", url: "https://mcp.canva.com/mcp", about: "Designs: search, create and export." },
+    { id: "vercel", label: "Vercel", url: "https://mcp.vercel.com/", about: "Projects, deployments and logs." },
+    { id: "cloudflare", label: "Cloudflare", url: "https://mcp.cloudflare.com/mcp", about: "Workers, DNS and your Cloudflare account." },
+];
+const loopback = (value) => { try {
+    const url = new URL(value);
+    return url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+}
+catch {
+    return false;
+} };
+/**
+ * The list, with one service standing in on this computer when the person
+ * running Toolroll says so ("stripe|Stripe|http://127.0.0.1:5123/mcp"
+ * in TOOLROLL_TEST_CONNECT): how the end-to-end check signs in for
+ * real without a real account. Only a loopback address is taken.
+ */
+export function oneClickServices(environment = process.env) {
+    const [id = "", label = "", url = ""] = (envValue(environment, "TEST_CONNECT") ?? "").split("|");
+    if (!/^[a-z0-9-]{1,40}$/.test(id) || label === "" || !loopback(url))
+        return ONE_CLICK;
+    const standIn = { id, label, url, about: ONE_CLICK.find(one => one.id === id)?.about ?? "A service on this computer." };
+    return ONE_CLICK.some(one => one.id === id) ? ONE_CLICK.map(one => one.id === id ? standIn : one) : [...ONE_CLICK, standIn];
+}
+export const oneClickOf = (id) => oneClickServices().find(one => one.id === id) ?? null;
+/** Where each service stands in a project: connected by signing in, open to connect, or its name taken by a tool set up another way. */
+export function connectionsOf(store, repo) {
+    const tools = projectToolsOf(store, repo);
+    return oneClickServices().map(service => {
+        const had = tools.find(one => one.name === service.id);
+        return { id: service.id, label: service.label, about: service.about, state: had === undefined ? "open" : had.spec.url === service.url && had.spec.bearer === ACCESS ? "connected" : "taken" };
+    });
+}
+/** The secrets a connected tool keeps: the bearer the MCP server takes, and what refreshing it needs. */
+const ACCESS = "OAUTH_ACCESS_TOKEN", REFRESH = "OAUTH_REFRESH_TOKEN", CLIENT = "OAUTH_CLIENT_ID", CLIENT_SECRET = "OAUTH_CLIENT_SECRET", TOKEN_URL = "OAUTH_TOKEN_URL", EXPIRES = "OAUTH_EXPIRES_AT", RESOURCE = "OAUTH_RESOURCE";
+/** Where a service sends the person back after they sign in. */
+export const CONNECT_CALLBACK = "/settings/tools/connected";
+const VISIT_MS = 15 * 60_000, RENEW_RETRY_MS = 5 * 60_000;
+const renewTried = new Map();
+const json = async (fetcher, url) => {
+    try {
+        const answer = await fetcher(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+        if (!answer.ok)
+            return null;
+        const body = await answer.json();
+        return body !== null && typeof body === "object" && !Array.isArray(body) ? body : null;
+    }
+    catch {
+        return null;
+    }
+};
+const secure = (value) => { try {
+    return new URL(value).protocol === "https:";
+}
+catch {
+    return false;
+} };
+/** A server's sign-in: the resource metadata its 401 names (or the well-known one), then its authorization server's metadata. */
+export async function discoverSignIn(mcpUrl, fetcher = fetch) {
+    const mcp = new URL(mcpUrl);
+    // Sign-in addresses are https, except a stand-in on this computer whose own sign-in is here too (OAuth's loopback exception).
+    const https = (value) => typeof value === "string" && (secure(value) || (loopback(mcpUrl) && loopback(value)));
+    let pointer = null;
+    try {
+        const probe = await fetcher(mcpUrl, { method: "POST", headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "toolroll", version: "1" } } }), signal: AbortSignal.timeout(10_000) });
+        pointer = /resource_metadata="([^"]+)"/.exec(probe.headers.get("www-authenticate") ?? "")?.[1] ?? null;
+        await probe.body?.cancel();
+    }
+    catch {
+        pointer = null;
+    }
+    const resource = (pointer !== null && https(pointer) ? await json(fetcher, pointer) : null)
+        ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource${mcp.pathname === "/" ? "" : mcp.pathname}`)
+        ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource`);
+    const issuers = Array.isArray(resource?.["authorization_servers"]) ? resource["authorization_servers"].filter(https) : [];
+    const issuer = new URL(issuers[0] ?? mcp.origin);
+    const path = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/$/, "");
+    const meta = await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server${path}`)
+        ?? await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server`)
+        ?? await json(fetcher, `${issuer.origin}/.well-known/openid-configuration`);
+    if (meta === null || !https(meta["authorization_endpoint"]) || !https(meta["token_endpoint"]) || !https(meta["registration_endpoint"]))
+        return null;
+    const methods = Array.isArray(meta["code_challenge_methods_supported"]) ? meta["code_challenge_methods_supported"] : ["S256"];
+    if (!methods.includes("S256"))
+        return null;
+    const scopes = Array.isArray(resource?.["scopes_supported"]) ? resource["scopes_supported"].filter((one) => typeof one === "string") : [];
+    // A token is for the resource the server names (Stripe's has no trailing slash), when it names one.
+    const named = resource?.["resource"];
+    return { authorize: meta["authorization_endpoint"], token: meta["token_endpoint"], register: meta["registration_endpoint"], scopes: scopes.slice(0, 20), resource: https(named) ? named : null };
+}
+/**
+ * Start connecting a service: find its sign-in, register this console as a
+ * client, and hand back the address to send the person to (and the visit the
+ * callback finishes). The person's password was checked before this.
+ */
+export async function startConnect(input, fetcher = fetch, now = Date.now()) {
+    const service = oneClickOf(input.service);
+    if (service === null)
+        return { ok: false, said: "Choose a service from the list." };
+    const server = await discoverSignIn(service.url, fetcher);
+    if (server === null)
+        return { ok: false, said: `${service.label} didn't offer a sign-in just now. Try again in a minute.` };
+    const redirect = `${input.origin}${CONNECT_CALLBACK}`;
+    let clientId, clientSecret;
+    try {
+        const registered = await fetcher(server.register, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, signal: AbortSignal.timeout(10_000),
+            body: JSON.stringify({ client_name: "Toolroll", redirect_uris: [redirect], grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], token_endpoint_auth_method: "none" }) });
+        const body = await registered.json();
+        if (!registered.ok || typeof body.client_id !== "string")
+            return { ok: false, said: `${service.label} didn't let Toolroll register (HTTP ${registered.status}).` };
+        clientId = body.client_id;
+        clientSecret = typeof body.client_secret === "string" ? body.client_secret : null;
+    }
+    catch {
+        return { ok: false, said: `${service.label} couldn't be reached.` };
+    }
+    const resource = server.resource ?? service.url;
+    const verifier = randomBytes(32).toString("base64url");
+    const state = randomBytes(24).toString("base64url");
+    const go = new URL(server.authorize);
+    go.searchParams.set("response_type", "code");
+    go.searchParams.set("client_id", clientId);
+    go.searchParams.set("redirect_uri", redirect);
+    go.searchParams.set("code_challenge", createHash("sha256").update(verifier).digest("base64url"));
+    go.searchParams.set("code_challenge_method", "S256");
+    go.searchParams.set("state", state);
+    go.searchParams.set("resource", resource);
+    if (server.scopes.length > 0)
+        go.searchParams.set("scope", server.scopes.join(" "));
+    return { ok: true, go: go.toString(), state, visit: { service: service.id, repo: input.repo, by: input.by, kit: input.kit ?? null, verifier, clientId, clientSecret, token: server.token, resource, redirect, expires: now + VISIT_MS } };
+}
+/** The spec a connected service joins the project with: its MCP address, signed in with the token its sign-in gave. */
+export function connectedSpec(serviceId) {
+    const service = oneClickOf(serviceId);
+    if (service === null)
+        return null;
+    return { name: service.id, transport: "http", command: null, args: [], url: service.url, bearer: ACCESS, headerSecrets: {},
+        secrets: [ACCESS, REFRESH, CLIENT, CLIENT_SECRET, TOKEN_URL, EXPIRES, RESOURCE].map(name => ({ name, optional: name !== ACCESS })), about: `${service.label}: ${service.about} Connected by signing in.` };
+}
+const tokensFrom = (body, now) => ({
+    access: typeof body["access_token"] === "string" ? body["access_token"] : null,
+    refresh: typeof body["refresh_token"] === "string" ? body["refresh_token"] : null,
+    expires: typeof body["expires_in"] === "number" && body["expires_in"] > 0 ? new Date(now + body["expires_in"] * 1000).toISOString() : null,
+});
+/**
+ * Finish connecting: trade the code for tokens, add the tool to the project
+ * (or refresh its sign-in, when it's there already), keep the tokens in its
+ * secrets file, and test it.
+ */
+export async function finishConnect(store, visit, code, now, options = {}) {
+    const service = oneClickOf(visit.service);
+    const fetcher = options.fetcher ?? fetch, home = options.home ?? homedir();
+    const spec = connectedSpec(service.id);
+    const had = projectToolsOf(store, visit.repo).find(one => one.name === spec.name);
+    if (had !== undefined && (had.spec.url !== spec.url || had.spec.bearer !== ACCESS))
+        return { ok: false, said: `This project already has a tool called ${spec.name}, set up another way. Remove it on this page to connect ${service.label} by signing in.` };
+    let body;
+    try {
+        const answer = await fetcher(visit.token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
+            body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: visit.redirect, client_id: visit.clientId, code_verifier: visit.verifier, resource: visit.resource, ...(visit.clientSecret === null ? {} : { client_secret: visit.clientSecret }) }) });
+        body = await answer.json();
+        if (!answer.ok)
+            return { ok: false, said: `${service.label} didn't finish the sign-in (${typeof body["error"] === "string" ? body["error"] : `HTTP ${answer.status}`}).` };
+    }
+    catch {
+        return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
+    }
+    const tokens = tokensFrom(body, now.getTime());
+    if (tokens.access === null)
+        return { ok: false, said: `${service.label} didn't send a sign-in token.` };
+    if (had === undefined) {
+        const added = addToolTo(store, visit.repo, spec, `${service.label}, connected by signing in`, visit.by, now, { home });
+        if (!added.ok)
+            return { ok: false, said: added.message };
+    }
+    setToolSecrets(visit.repo, spec.name, { [ACCESS]: tokens.access, [CLIENT]: visit.clientId, [TOKEN_URL]: visit.token, [RESOURCE]: visit.resource,
+        ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }), ...(visit.clientSecret === null ? {} : { [CLIENT_SECRET]: visit.clientSecret }) }, home);
+    if (options.test === false)
+        return { ok: true, said: `${service.label} is connected.` };
+    const tested = await testToolOf(store, visit.repo, spec.name, now, { home, ...(options.omitEnv === undefined ? {} : { omitEnv: options.omitEnv }) });
+    return tested?.ok ? { ok: true, said: `${service.label} is connected: ${tested.tools.length} action${tested.tools.length === 1 ? "" : "s"}. Let a teammate use it from its page.` }
+        : { ok: true, said: `${service.label} is signed in, but its test didn't pass yet: ${tested?.problem ?? "no answer"}.` };
+}
+/** Keep connected services signed in: any token expiring within ten minutes is refreshed (the worker's pass, and before a teammate's call). */
+export async function refreshConnections(store, repos, now, options = {}) {
+    const fetcher = options.fetcher ?? fetch, home = options.home ?? homedir();
+    const report = { refreshed: 0, problems: [] };
+    for (const repo of repos)
+        for (const tool of projectToolsOf(store, repo)) {
+            if (tool.spec.bearer !== ACCESS)
+                continue;
+            const values = readToolSecrets(repo, tool.name, home);
+            const expires = values[EXPIRES] === undefined ? null : Date.parse(values[EXPIRES]);
+            if (expires === null || Number.isNaN(expires) || expires - now.getTime() > 10 * 60_000 || values[REFRESH] === undefined || values[TOKEN_URL] === undefined || values[CLIENT] === undefined)
+                continue;
+            // One try every five minutes at most: a sign-in the service has revoked is said once in a while, not every pass.
+            const key = `${repo}\0${tool.name}`;
+            if (now.getTime() - (renewTried.get(key) ?? 0) < RENEW_RETRY_MS)
+                continue;
+            renewTried.set(key, now.getTime());
+            try {
+                const answer = await fetcher(values[TOKEN_URL], { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
+                    body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: values[REFRESH], client_id: values[CLIENT], ...(values[CLIENT_SECRET] === undefined ? {} : { client_secret: values[CLIENT_SECRET] }), ...(values[RESOURCE] === undefined ? {} : { resource: values[RESOURCE] }) }) });
+                const body = await answer.json();
+                const tokens = tokensFrom(body, now.getTime());
+                if (!answer.ok || tokens.access === null) {
+                    report.problems.push(`${tool.name}: its sign-in ran out; connect it again on the Tools page`);
+                    continue;
+                }
+                setToolSecrets(repo, tool.name, { [ACCESS]: tokens.access, ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }) }, home);
+                renewTried.delete(key);
+                report.refreshed++;
+            }
+            catch {
+                report.problems.push(`${tool.name}: couldn't reach it to renew its sign-in`);
+            }
+        }
+    return report;
+}

package/dist/mcp.d.ts

@@ -0,0 +1,27 @@
+import type { Store } from "./store.js";
+export declare const MODERN = "2026-07-28";
+export declare const LEGACY = "2025-11-25";
+/** The modern revision namespaces its per-request metadata. */
+export declare const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_SERVER = "io.modelcontextprotocol/serverInfo";
+export declare const META_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/** The revision's own error code for an unsupported protocol version. */
+export declare const UNSUPPORTED_VERSION = -32022;
+export type McpIo = {
+    onLine: (handler: (line: string) => void) => void;
+    onEof: (handler: () => void) => void;
+    write: (line: string) => void;
+    log: (line: string) => void;
+    exit: (code: number) => void;
+};
+export type McpOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unauthenticated" | "revoked" | "schema";
+    message: string;
+};
+/** Serve until EOF. The store is already open through the non-migrating
+ * door; the token was startup-verified by the caller (and dies here again
+ * if it does not hold). */
+export declare function serveMcp(store: Store, token: string, io: McpIo, clock?: () => Date, enrolled?: readonly string[] | null, evidenceRoot?: string): McpOutcome;