@autolane/courier-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autolane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @autolane/courier-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use [Courier by Autolane](https://docs.goautolane.com/courier/get-started) from an AI agent on any machine, including one with no browser: a server, a container, or a computer you reach over SSH.
+
+This package runs a small MCP server on your machine. It links to your phone once, keeps its own login, and passes your agent's requests to Autolane at `https://mcp.goautolane.com/courier-mcp`. Any agent that can run a local (stdio) MCP server can use it, even one without OAuth.
+
+## You probably don't need this package
+
+Most AI assistants connect to Courier by Autolane directly: add `https://mcp.goautolane.com/courier-mcp` as a custom connector or MCP server, link your phone, and you're done. Nothing to install.
+
+- **Claude** (claude.ai, Claude Desktop, phone apps): Customize, Connectors, + Add, Add custom connector. Name `Courier by Autolane`, URL `https://mcp.goautolane.com/courier-mcp`. Select Connect, then enter your mobile number and the 6-digit code Autolane texts you.
+- **ChatGPT** (web, and your dots): chatgpt.com/plugins, +, Add custom MCP server. Name `Courier by Autolane`, Server URL `https://mcp.goautolane.com/courier-mcp`, Authentication OAuth (leave client ID and secret empty). Select Connect and link your phone.
+- **Claude Code**: `claude mcp add --transport http --scope user courier-by-autolane https://mcp.goautolane.com/courier-mcp`, then `claude mcp login courier-by-autolane`.
+- **Codex** (CLI, IDE extension, ChatGPT desktop app): `codex mcp add courier-by-autolane --url https://mcp.goautolane.com/courier-mcp`. Codex opens your browser; if not, run `codex mcp login courier-by-autolane`.
+- **OpenClaw**: `openclaw mcp add courier-by-autolane --url https://mcp.goautolane.com/courier-mcp --transport streamable-http --auth oauth`, then `openclaw mcp login courier-by-autolane`.
+- **Hermes**: add this custom MCP entry, then open its config and select Retry, then Authorize:
+
+  ```json
+  { "mcpServers": { "Courier by Autolane": { "url": "https://mcp.goautolane.com/courier-mcp", "auth": "oauth" } } }
+  ```
+
+- **Muse** (Meta AI): ask "Connect the Courier by Autolane MCP at https://mcp.goautolane.com/courier-mcp", open the link it shows, and check the code matches.
+
+Full guides: [docs.goautolane.com/courier/get-started](https://docs.goautolane.com/courier/get-started).
+
+**Terminal agent on another machine** (over SSH or on a server)? After you link your phone, the Autolane page asks where the agent is running. Pick **On another computer** and paste the link it shows where the agent asks for one. If the agent doesn't ask, open "isn't asking for a link?" and run the `curl` command it shows on the agent's machine.
+
+## When to use this package
+
+Use it when your agent runs on a machine with no browser and you'd rather link with a code from your phone, or when your agent can run a local (stdio) MCP server but can't sign in to one with OAuth.
+
+### Link your phone
+
+On the machine where your agent runs:
+
+    npx -y @autolane/courier-mcp login --no-browser
+
+Open the link it prints on any device (your phone works), check the page shows the same code, and enter your mobile number and the 6-digit code Autolane texts you. The command finishes by itself. Leave out `--no-browser` to have it open the link in a browser on this machine.
+
+Courier by Autolane is invite-only for now. If the page says the service isn't available for your number, [join the waitlist](https://goautolane.com/autolane-courier).
+
+### Add it to your agent
+
+Claude Code:
+
+    claude mcp add --scope user courier-by-autolane -- npx -y @autolane/courier-mcp
+
+Any other agent: add a local (stdio) MCP server with the command `npx` and the arguments `-y @autolane/courier-mcp`.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `npx -y @autolane/courier-mcp` | Runs the MCP server on stdio. Your agent's config runs this. |
+| `login [--no-browser]` | Links this machine to your phone. |
+| `logout` | Revokes this machine's link and removes it. |
+| `status` | Shows whether this machine is linked. |
+
+## Where the login lives
+
+`~/.config/autolane/courier-mcp.json` (or `$XDG_CONFIG_HOME/autolane/` when set; `%APPDATA%\autolane\` on Windows), readable only by you. It holds a short-lived access token and a refresh token, never your phone number. Several agents on one machine can share it. Run `logout` to remove it.
+
+## Help
+
+support@goautolane.com

package/dist/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+import { describeError } from './errors.js';
+main(process.argv.slice(2), { env: process.env, out: (line) => console.log(line), err: (line) => console.error(line) }).then((code) => {
+    if (code !== null)
+        process.exitCode = code;
+}, (error) => {
+    console.error(describeError(error));
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,88 @@
+// The commands (spec section 4.1). Everything a command prints goes through `out`/`err`; serve prints nothing to
+// stdout, which carries MCP messages.
+import { parseArgs } from 'node:util';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { RELINK, VERSION, configDir, serverUrl } from './config.js';
+import { describeError } from './errors.js';
+import { login } from './login.js';
+import { discover, revoke } from './oauth.js';
+import { createProxy } from './proxy.js';
+import { createSession } from './session.js';
+import { fileStore } from './store.js';
+export const USAGE = `Usage: npx -y @autolane/courier-mcp [command]
+
+  (no command)          Run the MCP server on stdio; this is what your agent's config runs
+  login [--no-browser]  Link this machine to your phone
+  logout                Remove this machine's link
+  status                Show whether this machine is linked
+
+AUTOLANE_COURIER_URL changes the server (default https://mcp.goautolane.com/courier-mcp).`;
+/** Runs one command and resolves to its exit code, or to null for serve, which keeps running. */
+export async function main(argv, deps) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { 'no-browser': { type: 'boolean', default: false }, help: { type: 'boolean', short: 'h', default: false }, version: { type: 'boolean', default: false } },
+    });
+    if (values.help) {
+        deps.out(USAGE);
+        return 0;
+    }
+    if (values.version) {
+        deps.out(VERSION);
+        return 0;
+    }
+    const server = serverUrl(deps.env);
+    const store = fileStore(configDir(deps.env), server);
+    const now = deps.now ?? Date.now;
+    const [command = 'serve', ...rest] = positionals;
+    if (rest.length > 0) {
+        deps.err(USAGE);
+        return 2;
+    }
+    switch (command) {
+        case 'login':
+            await login({ server, store, noBrowser: values['no-browser'], print: deps.out, openUrl: deps.openUrl, fetch: deps.fetch, sleep: deps.sleep, now });
+            return 0;
+        case 'logout':
+            // Under the lock: a refresh in an agent must not rotate the token between our read and our revoke.
+            return store.withLock(async () => {
+                const saved = await store.read();
+                if (!saved) {
+                    deps.out('This machine is not linked.');
+                    return 0;
+                }
+                try {
+                    await revoke(await discover(server, deps.fetch), saved.client_id, saved.refresh_token, deps.fetch);
+                }
+                catch (error) {
+                    deps.err(`Could not reach Autolane to revoke the link (${describeError(error)}); removing it from this machine anyway.`);
+                }
+                await store.remove();
+                deps.out('Logged out. This machine is no longer linked.');
+                return 0;
+            });
+        case 'status': {
+            const saved = await store.read();
+            if (!saved) {
+                deps.out(`Not linked to ${server}.`);
+                return 1;
+            }
+            const access = saved.access_expires_at > now() ? `valid until ${new Date(saved.access_expires_at).toISOString()}` : 'expired; it refreshes on the next call';
+            deps.out(`Linked to ${server}.\nAccess token ${access}.\nToken file: ${store.path}`);
+            return 0;
+        }
+        case 'serve': {
+            if (!(await store.read())) {
+                deps.err(RELINK);
+                return 1;
+            }
+            const session = createSession({ store, endpoints: () => discover(server, deps.fetch), fetch: deps.fetch, now });
+            await createProxy({ server, session, fetch: deps.fetch }).connect(deps.transport?.() ?? new StdioServerTransport());
+            return null;
+        }
+        default:
+            deps.err(USAGE);
+            return 2;
+    }
+}

package/dist/config.js

@@ -0,0 +1,34 @@
+// Where the package talks to, and where it keeps its login (spec section 4.4).
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { posix, win32, join } from 'node:path';
+export const DEFAULT_SERVER = 'https://mcp.goautolane.com/courier-mcp';
+export const RELINK = 'Not linked. Run: npx -y @autolane/courier-mcp login --no-browser';
+/** The client_name the phone page shows: "Link your phone to Courier by Autolane MCP". */
+export const CLIENT_NAME = 'Courier by Autolane MCP';
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1']);
+/** The courier MCP endpoint: AUTOLANE_COURIER_URL (sandbox, or a local dev server over http), else production. */
+export function serverUrl(env = process.env) {
+    const raw = env.AUTOLANE_COURIER_URL?.trim() || DEFAULT_SERVER;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`AUTOLANE_COURIER_URL is not a URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))) {
+        throw new Error(`AUTOLANE_COURIER_URL must be an https URL (or http on localhost): ${raw}`);
+    }
+    return url.toString().replace(/\/$/, '');
+}
+/** The token file's directory: %APPDATA%\autolane on Windows, else $XDG_CONFIG_HOME/autolane or ~/.config/autolane. */
+export function configDir(env = process.env, platform = process.platform) {
+    // The XDG spec says to ignore a relative path, and a relative APPDATA would put the token file in the working directory.
+    const absolute = (path) => (path && (platform === 'win32' ? win32 : posix).isAbsolute(path) ? path : undefined);
+    const appData = platform === 'win32' ? absolute(env.APPDATA) : undefined;
+    if (appData)
+        return join(appData, 'autolane');
+    return join(absolute(env.XDG_CONFIG_HOME) ?? join(homedir(), '.config'), 'autolane');
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+// One way to say why something failed, for the CLI and the proxy alike.
+/** An error's message, with its cause's in parentheses: fetch says only "fetch failed" and keeps the reason in `cause`. */
+export function describeError(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    if (!(cause instanceof Error))
+        return error.message;
+    // A dual-stack connect failure is an AggregateError with no message; the reason is in its first inner error.
+    const inner = cause instanceof AggregateError ? cause.errors[0] : undefined;
+    const reason = cause.message || inner?.message || inner?.code || cause.code || cause.name;
+    return `${error.message} (${reason})`;
+}
+/** Text from a server, safe to print: control characters (an escape sequence, a newline) are dropped. */
+// eslint-disable-next-line no-control-regex
+export const plain = (text) => text.replace(/[\x00-\x1f\x7f]/g, '');

package/dist/login.js

@@ -0,0 +1,49 @@
+// `login`: RFC 8628 from a terminal (spec section 4.2). Print the link and code, open the link unless
+// --no-browser, wait while the user links their phone on any device, then save the tokens.
+import { spawn } from 'node:child_process';
+import { CLIENT_NAME } from './config.js';
+import { describeError, plain } from './errors.js';
+import { OAuthError, discover, pollDevice, register, revoke, startDevice } from './oauth.js';
+import { savedFrom } from './session.js';
+export async function login(opts) {
+    const endpoints = await discover(opts.server, opts.fetch);
+    const savedClient = (await opts.store.read())?.client_id;
+    let clientId = savedClient ?? (await register(endpoints, CLIENT_NAME, opts.fetch));
+    let start;
+    try {
+        start = await startDevice(endpoints, clientId, opts.fetch);
+    }
+    catch (error) {
+        // The server forgot the saved client: register a new one, once.
+        if (!savedClient || !(error instanceof OAuthError) || error.code !== 'invalid_client')
+            throw error;
+        clientId = await register(endpoints, CLIENT_NAME, opts.fetch);
+        start = await startDevice(endpoints, clientId, opts.fetch);
+    }
+    // The link comes from the server's reply. Print and open the parsed form, and open it only on the server's own origin.
+    const url = new URL(start.verification_uri_complete ?? start.verification_uri);
+    opts.print(`Open this link on any device (your phone works), then link your phone:\n\n  ${plain(url.href)}\n\nThe page should show the code ${plain(start.user_code)}. Waiting...`);
+    if (!opts.noBrowser && url.origin === new URL(opts.server).origin)
+        (opts.openUrl ?? openBrowser)(url.href);
+    const tokens = await pollDevice(endpoints, clientId, start, { fetch: opts.fetch, sleep: opts.sleep, now: opts.now });
+    // Save under the lock, so a refresh running in an agent cannot interleave with it.
+    const previous = await opts.store.withLock(async () => {
+        const before = await opts.store.read();
+        await opts.store.write(savedFrom({ server: opts.server, client_id: clientId }, tokens, (opts.now ?? Date.now)()));
+        return before;
+    });
+    // The old login is replaced, so revoke it; best effort, since the new one already works.
+    if (previous) {
+        await revoke(endpoints, previous.client_id, previous.refresh_token, opts.fetch).catch((error) => {
+            opts.print(`Could not revoke the previous link (${describeError(error)}); it expires on its own.`);
+        });
+    }
+    opts.print('Linked. Your agent can use Courier by Autolane now.');
+}
+/** Best effort: on a machine with no browser nothing opens, and the printed link is the way in. */
+export function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? [`${process.env.SystemRoot ?? 'C:\\Windows'}\\explorer.exe`, [url]] : ['xdg-open', [url]];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => { });
+    child.unref();
+}

package/dist/oauth.js

@@ -0,0 +1,126 @@
+// The courier authorization server, over fetch: RFC 8414 discovery, RFC 7591 registration of a device-only
+// public client (AUT-3861), the RFC 8628 device grant (contract A91), refresh with rotation, RFC 7009 revoke.
+import { describeError, plain } from './errors.js';
+/** No request may hang: a refresh stuck past the lock's stale limit would let a second process reuse the refresh token. */
+const REQUEST_TIMEOUT_MS = 10_000;
+const timeout = () => AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+/** Every request refuses redirects: the endpoints are fixed, and a redirect would carry the form body, or a bearer, elsewhere. */
+const guard = () => ({ signal: timeout(), redirect: 'error' });
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+export class OAuthError extends Error {
+    code;
+    status;
+    constructor(code, description, status, 
+    /** The endpoint path, for an error the server gave no description of. */
+    from) {
+        super(description ? `${code}: ${description}` : from ? `${code} from ${from}` : code);
+        this.code = code;
+        this.status = status;
+    }
+}
+const ENDPOINT_KEYS = ['registration_endpoint', 'device_authorization_endpoint', 'token_endpoint', 'revocation_endpoint'];
+async function json(res, url) {
+    const parsed = await res.json().catch(() => null);
+    // A body that is not an object (null, a number) is no better than none.
+    const body = (typeof parsed === 'object' && parsed !== null ? parsed : {});
+    if (!res.ok) {
+        const description = typeof body.error_description === 'string' ? body.error_description : undefined;
+        throw new OAuthError(typeof body.error === 'string' ? body.error : `http_${res.status}`, description, res.status, new URL(url).pathname);
+    }
+    return body;
+}
+/** A 200 that is not a token set must not reach the saved file, where the missing fields would drop the refresh token. */
+async function tokenSet(res, url) {
+    const body = await json(res, url);
+    if (typeof body.access_token !== 'string' || typeof body.refresh_token !== 'string' || typeof body.expires_in !== 'number' || !Number.isFinite(body.expires_in)) {
+        throw new OAuthError('invalid_response', 'The token response is missing a field', 502);
+    }
+    return body;
+}
+const form = (fields) => ({
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(fields).toString(),
+    ...guard(),
+});
+/** RFC 8414 section 3.1: the issuer is the server URL (contract A97), so its path goes after the well-known prefix. */
+export async function discover(server, f = fetch) {
+    const url = new URL(server);
+    const metadataUrl = `${url.origin}/.well-known/oauth-authorization-server${url.pathname.replace(/\/$/, '')}`;
+    const meta = await json(await f(metadataUrl, guard()), metadataUrl);
+    for (const key of ENDPOINT_KEYS) {
+        if (typeof meta[key] !== 'string')
+            throw new Error(`${server} does not offer ${key}; is it a Courier MCP URL?`);
+    }
+    // A metadata document is trusted only if it names this server and keeps every endpoint on its origin.
+    if (meta.issuer !== server)
+        throw new Error(`${server} metadata has the wrong issuer ${plain(String(meta.issuer))}; is it a Courier MCP URL?`);
+    for (const key of ENDPOINT_KEYS) {
+        if (new URL(meta[key]).origin !== url.origin)
+            throw new Error(`${server} metadata puts ${key} on another origin: ${plain(meta[key])}`);
+    }
+    return meta;
+}
+/** A client with no redirect URI links only through the device grant (AUT-3861). */
+export async function register(endpoints, clientName, f = fetch) {
+    const res = await f(endpoints.registration_endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ client_name: clientName, redirect_uris: [], grant_types: [DEVICE_GRANT, 'refresh_token'], token_endpoint_auth_method: 'none' }),
+        ...guard(),
+    });
+    const { client_id } = await json(res, endpoints.registration_endpoint);
+    if (typeof client_id !== 'string')
+        throw new OAuthError('invalid_response', 'The registration response has no client_id', 502);
+    return client_id;
+}
+export async function startDevice(endpoints, clientId, f = fetch) {
+    const reply = await json(await f(endpoints.device_authorization_endpoint, form({ client_id: clientId })), endpoints.device_authorization_endpoint);
+    const text = (value) => typeof value === 'string';
+    if (!text(reply.device_code) || !text(reply.user_code) || !text(reply.verification_uri) || typeof reply.expires_in !== 'number' || !Number.isFinite(reply.expires_in) || (reply.interval !== undefined && typeof reply.interval !== 'number')) {
+        throw new OAuthError('invalid_response', 'The device authorization response is malformed', 502);
+    }
+    return reply;
+}
+/** A request that did not complete: a timeout, or fetch's "fetch failed" (its reason is in `cause`). Any other error is a bug, and stops the poll. */
+const isTransient = (error) => error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError' || (error instanceof TypeError && error.message === 'fetch failed'));
+/** RFC 8628 sections 3.4 and 3.5: wait `interval` seconds between polls, five more after each slow_down, until the user links or the code expires. */
+export async function pollDevice(endpoints, clientId, start, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = opts.now ?? Date.now;
+    // The server still accepts an approval for 30 seconds after expires_in, so the local deadline does too.
+    const deadline = now() + start.expires_in * 1000 + 30_000;
+    let interval = start.interval ?? 5;
+    let lastError;
+    for (;;) {
+        await sleep(interval * 1000);
+        if (now() > deadline) {
+            const last = lastError === undefined ? '' : ` (last error: ${describeError(lastError)})`;
+            throw new OAuthError('expired_token', `The link expired before your phone was linked; run login again${last}`, 400);
+        }
+        try {
+            return await tokenSet(await f(endpoints.token_endpoint, form({ grant_type: DEVICE_GRANT, device_code: start.device_code, client_id: clientId })), endpoints.token_endpoint);
+        }
+        catch (error) {
+            if (error instanceof OAuthError && error.code === 'authorization_pending')
+                continue;
+            // RFC 8628 section 3.5: a slow_down, a dropped connection, a timeout or a 5xx all mean "wait longer and ask again".
+            if ((error instanceof OAuthError && (error.code === 'slow_down' || (error.status >= 500 && error.code !== 'invalid_response'))) || isTransient(error)) {
+                if (!(error instanceof OAuthError && error.code === 'slow_down'))
+                    lastError = error;
+                interval += 5;
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+export async function refresh(endpoints, clientId, refreshToken, f = fetch) {
+    return tokenSet(await f(endpoints.token_endpoint, form({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId })), endpoints.token_endpoint);
+}
+export async function revoke(endpoints, clientId, token, f = fetch) {
+    const res = await f(endpoints.revocation_endpoint, form({ token, token_type_hint: 'refresh_token', client_id: clientId }));
+    if (!res.ok)
+        throw new OAuthError(`http_${res.status}`, undefined, res.status, new URL(endpoints.revocation_endpoint).pathname);
+}

package/dist/proxy.js

@@ -0,0 +1,99 @@
+// The stdio MCP server an agent runs, in front of /courier-mcp (spec section 4.3). It forwards tools and
+// resources, everything the courier server offers, sending the session's bearer token on every request.
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, McpError, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { RELINK, VERSION } from './config.js';
+import { describeError } from './errors.js';
+import { NotLinkedError } from './session.js';
+/** fetch with the bearer token; a 401 forces one refresh and resends (MCP request bodies are strings, so they can go twice). */
+export function bearerFetch(session, base = fetch) {
+    return async (input, init) => {
+        const send = async (force) => {
+            const headers = new Headers(init?.headers);
+            headers.set('authorization', `Bearer ${await session.accessToken({ force })}`);
+            return base(input, { ...init, headers });
+        };
+        const first = await send(false);
+        if (first.status !== 401)
+            return first;
+        await first.body?.cancel();
+        return send(true);
+    };
+}
+/** Shown instead of the courier tools when the login is gone, so the agent can tell the user how to link. */
+const LOGIN_TOOL = 'autolane_courier_login_needed';
+const loginNeeded = `${RELINK}, then restart your agent.`;
+/** One line, no token: only the error's message, newlines folded. */
+const reportLine = (error) => `courier-mcp: ${describeError(error).replace(/\s+/g, ' ')}`;
+/** The agent sees only an error's message, so a failure that keeps its reason in `cause` is rethrown with it spelled out. */
+async function withCause(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        const text = describeError(error);
+        if (error instanceof NotLinkedError || error instanceof McpError || !(error instanceof Error) || text === error.message)
+            throw error;
+        throw new Error(text);
+    }
+}
+export function createProxy(opts) {
+    const write = opts.log ?? ((line) => console.error(line));
+    let closed = false;
+    // Closing aborts the upstream stream, and that abort is not worth a line.
+    const log = (line) => {
+        if (!closed)
+            write(line);
+    };
+    let remote = null;
+    /** Connects on first use, so the agent's handshake never waits on the network; a failed connect is retried next time. */
+    const connected = () => {
+        remote ??= (async () => {
+            const client = new Client({ name: 'autolane-courier-mcp', version: VERSION });
+            client.onerror = (error) => log(reportLine(error));
+            await client.connect(new StreamableHTTPClientTransport(new URL(opts.server), { fetch: bearerFetch(opts.session, opts.fetch) }));
+            return client;
+        })().catch((error) => {
+            remote = null;
+            throw error;
+        });
+        return remote;
+    };
+    const proxy = new Server({ name: 'autolane-courier', version: VERSION }, { capabilities: { tools: {}, resources: {} } });
+    proxy.onerror = (error) => log(reportLine(error));
+    proxy.onclose = () => {
+        closed = true;
+        const upstream = remote;
+        remote = null;
+        void upstream?.then((client) => client.close(), () => { });
+    };
+    proxy.setRequestHandler(ListToolsRequestSchema, async (req, extra) => {
+        try {
+            return await withCause(async () => (await connected()).listTools(req.params, { signal: extra.signal }));
+        }
+        catch (error) {
+            if (error instanceof NotLinkedError)
+                return { tools: [{ name: LOGIN_TOOL, description: loginNeeded, inputSchema: { type: 'object', properties: {} } }] };
+            throw error;
+        }
+    });
+    proxy.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+        // The agent shows a tool error to the user, so the relink line reaches them.
+        if (req.params.name === LOGIN_TOOL)
+            return { isError: true, content: [{ type: 'text', text: loginNeeded }] };
+        try {
+            return (await withCause(async () => (await connected()).callTool(req.params, undefined, { signal: extra.signal })));
+        }
+        catch (error) {
+            if (error instanceof NotLinkedError)
+                return { isError: true, content: [{ type: 'text', text: error.message }] };
+            throw error;
+        }
+    });
+    proxy.setRequestHandler(ListResourcesRequestSchema, async (req, extra) => withCause(async () => (await connected()).listResources(req.params, { signal: extra.signal })));
+    proxy.setRequestHandler(ListResourceTemplatesRequestSchema, async (req, extra) => withCause(async () => (await connected()).listResourceTemplates(req.params, { signal: extra.signal })));
+    proxy.setRequestHandler(ReadResourceRequestSchema, async (req, extra) => withCause(async () => (await connected()).readResource(req.params, { signal: extra.signal })));
+    return proxy;
+}

package/dist/session.js

@@ -0,0 +1,49 @@
+// The access token to send. Near expiry, or after a 401, it refreshes under the store's lock, re-reading the file
+// inside it: a second agent that waited uses the token the first just rotated, since reusing the old refresh token
+// would make the server revoke the whole family (no grace window).
+import { RELINK } from './config.js';
+import { OAuthError, refresh } from './oauth.js';
+/** Refresh when less than this is left on the access token. */
+const REFRESH_EARLY_MS = 60_000;
+export class NotLinkedError extends Error {
+    constructor() {
+        super(RELINK);
+        this.name = 'NotLinkedError';
+    }
+}
+export function savedFrom(base, tokens, now) {
+    return { server: base.server, client_id: base.client_id, access_token: tokens.access_token, refresh_token: tokens.refresh_token, access_expires_at: now + tokens.expires_in * 1000 };
+}
+export function createSession(opts) {
+    const now = opts.now ?? Date.now;
+    return {
+        async accessToken({ force = false } = {}) {
+            const seen = await opts.store.read();
+            if (!seen)
+                throw new NotLinkedError();
+            if (!force && seen.access_expires_at - now() > REFRESH_EARLY_MS)
+                return seen.access_token;
+            // Look the endpoints up first, so only the refresh itself runs while the lock is held.
+            const endpoints = await opts.endpoints();
+            return opts.store.withLock(async () => {
+                const current = await opts.store.read();
+                if (!current)
+                    throw new NotLinkedError();
+                if (current.refresh_token !== seen.refresh_token)
+                    return current.access_token;
+                let tokens;
+                try {
+                    tokens = await refresh(endpoints, current.client_id, current.refresh_token, opts.fetch);
+                }
+                catch (error) {
+                    // invalid_grant: the refresh token is spent or revoked. invalid_client: the server forgot this client. Both need a new login.
+                    if (error instanceof OAuthError && (error.code === 'invalid_grant' || error.code === 'invalid_client'))
+                        throw new NotLinkedError();
+                    throw error;
+                }
+                await opts.store.write(savedFrom(current, tokens, now()));
+                return tokens.access_token;
+            });
+        },
+    };
+}

package/dist/store.js

@@ -0,0 +1,101 @@
+// The login on disk (spec section 4.4): one JSON file, 0600 in a 0700 directory, replaced by rename.
+// The lock file serializes refreshes: the server rotates refresh tokens and revokes the whole family
+// when an old one is reused, so two agents sharing this file must never refresh at once.
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const isSaved = (value) => {
+    const v = value;
+    return typeof v === 'object' && v !== null && typeof v.server === 'string' && typeof v.client_id === 'string' && typeof v.access_token === 'string' && typeof v.refresh_token === 'string' && typeof v.access_expires_at === 'number';
+};
+const isMissing = (error) => error.code === 'ENOENT';
+export function fileStore(dir, server, opts = {}) {
+    const { staleMs = 30_000, waitMs = 30_000, pollMs = 100 } = opts;
+    const path = join(dir, 'courier-mcp.json');
+    const lockPath = join(dir, 'courier-mcp.lock');
+    const ensureDir = async () => {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        await chmod(dir, 0o700);
+    };
+    return {
+        path,
+        async read() {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return null;
+                throw error;
+            }
+            // A damaged file reads as not linked, so login can write over it. The parse error is dropped: V8 quotes the file in it.
+            const saved = (() => {
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return null;
+                }
+            })();
+            return isSaved(saved) && saved.server === server ? saved : null;
+        },
+        async write(saved) {
+            await ensureDir();
+            const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+            try {
+                await writeFile(tmp, `${JSON.stringify(saved, null, 2)}\n`, { mode: 0o600 });
+                await rename(tmp, path);
+            }
+            catch (error) {
+                await rm(tmp, { force: true });
+                throw error;
+            }
+        },
+        async remove() {
+            await rm(path, { force: true });
+        },
+        async withLock(fn) {
+            await ensureDir();
+            const deadline = Date.now() + waitMs;
+            const mine = `${process.pid} ${randomUUID()}\n`;
+            for (;;) {
+                try {
+                    const handle = await open(lockPath, 'wx', 0o600);
+                    try {
+                        await handle.writeFile(mine);
+                        await handle.close();
+                    }
+                    catch (writeError) {
+                        // We created the lock but could not finish it: do not strand it for the stale limit.
+                        await handle.close().catch(() => { });
+                        await rm(lockPath, { force: true });
+                        throw writeError;
+                    }
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                    const age = await stat(lockPath).then((s) => Date.now() - s.mtimeMs, () => 0);
+                    if (age > staleMs) {
+                        await rm(lockPath, { force: true });
+                        continue;
+                    }
+                    if (Date.now() > deadline)
+                        throw new Error(`Another courier-mcp process holds ${lockPath}; try again in a moment`);
+                    await new Promise((resolve) => setTimeout(resolve, pollMs));
+                }
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                // Another process may have taken a lock we held too long (stale takeover); never remove theirs.
+                // debt: two waiters can both judge the same lock stale and both take it, upgrade to an atomic rename takeover if that is seen.
+                if ((await readFile(lockPath, 'utf8').catch(() => null)) === mine)
+                    await rm(lockPath, { force: true });
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@autolane/courier-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "mcpName": "com.goautolane/courier",
+  "description": "Courier by Autolane MCP for agents on any machine: a local stdio server that links through the device grant",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "courier-mcp": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Autolane/courier-mcp.git"
+  },
+  "homepage": "https://github.com/Autolane/courier-mcp#readme",
+  "keywords": [
+    "mcp",
+    "autolane",
+    "courier",
+    "delivery"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  }
+}