@phenomenalorg/mcp 0.2.0

package/README.md

@@ -0,0 +1,111 @@
+# @phenomenalorg/mcp
+
+Connect an MCP client to **Phenomenal** — your school community's site, events,
+volunteers, store, donations and communications — over stdio.
+
+Phenomenal's MCP server is a normal remote MCP server at
+`https://api.phenomenal.org/mcp`, and **most clients no longer need this
+package**: they can speak Streamable HTTP directly and handle the browser
+sign-in themselves. Reach for this bridge when your MCP client only speaks
+stdio.
+
+## Connect without the bridge (preferred)
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http phenomenal https://api.phenomenal.org/mcp
+```
+
+Then run `/mcp` in Claude Code and pick **phenomenal** to sign in.
+
+**Codex CLI**
+
+```bash
+codex mcp add phenomenal --url https://api.phenomenal.org/mcp
+codex mcp login phenomenal
+```
+
+**Claude Desktop**
+
+Settings → **Connectors** → **Add custom connector** → paste
+`https://api.phenomenal.org/mcp` → **Connect**, and approve the browser
+consent screen.
+
+## Connect with the bridge (stdio-only clients)
+
+Add this to your client's MCP server config:
+
+```json
+{
+  "mcpServers": {
+    "phenomenal": {
+      "command": "npx",
+      "args": ["-y", "@phenomenalorg/mcp"]
+    }
+  }
+}
+```
+
+The first launch opens your browser, you approve access to your school's
+Phenomenal organization, and the bridge remembers the grant. There is no API
+key to create, paste or rotate.
+
+Point it somewhere else with a URL:
+
+```json
+{
+  "mcpServers": {
+    "phenomenal": {
+      "command": "npx",
+      "args": ["-y", "@phenomenalorg/mcp", "--url", "https://api.ph-dev.org/mcp"]
+    }
+  }
+}
+```
+
+## Command line
+
+```
+npx @phenomenalorg/mcp [<url>] [--url <url>] [--logout] [--version] [--help]
+```
+
+| Flag        | What it does                                                          |
+| ----------- | --------------------------------------------------------------------- |
+| `--url`     | The Phenomenal MCP endpoint. Default `https://api.phenomenal.org/mcp` |
+| `--logout`  | Forget the saved sign-in for that server and exit                     |
+| `--version` | Print the version and exit                                            |
+| `--help`    | Print usage and exit                                                  |
+
+Sign out of one server:
+
+```bash
+npx @phenomenalorg/mcp --logout
+npx @phenomenalorg/mcp --logout --url https://api.ph-dev.org/mcp
+```
+
+## Where your sign-in is kept
+
+`~/.phenomenal/mcp/<server>.json`, one file per server, written `0600` inside a
+`0700` directory. It holds the bridge's OAuth client registration and the
+access/refresh tokens issued to it — treat it exactly like an SSH private key.
+`--logout` deletes it; revoking the connection inside Phenomenal invalidates it
+from the other end.
+
+## How it works
+
+- Sign-in is OAuth 2.1 with **PKCE** and **dynamic client registration**. The
+  bridge registers itself as the public client `Phenomenal MCP`, opens
+  your browser, and catches the redirect on a loopback listener bound to
+  `127.0.0.1` — never a routable interface.
+- Once you have a token the bridge is a message pump: everything your client
+  writes on stdin goes to Phenomenal over Streamable HTTP and everything
+  Phenomenal sends back goes to stdout, notifications included.
+- `stdout` is the protocol stream. Every diagnostic the bridge prints goes to
+  `stderr`, so if something looks wrong, that is where to look.
+
+Requires Node 20 or newer.
+
+## Support
+
+Issues and questions: <https://github.com/PTO-pro/ptopro/issues>.

package/dist/auth.d.ts

@@ -0,0 +1,79 @@
+import { type OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+/**
+ * What the consent screen shows the person approving this bridge, and what
+ * Settings → Connected agents lists it as. Customer-facing, so it is the
+ * product name — not an implementation label (Bob's call, #2523).
+ */
+export declare const CLIENT_NAME = "Phenomenal MCP";
+export declare const CLIENT_URI = "https://phenomenal.org";
+export interface LoopbackListener {
+    readonly port: number;
+    readonly redirectUrl: string;
+    /** Resolves with the authorization code once the browser comes back. */
+    waitForCallback(): Promise<{
+        code: string;
+        state?: string;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * A stable port per server, so the registered `redirect_uris` survive between
+ * runs — a fresh ephemeral port every time would invalidate the registration
+ * and force a new consent screen on every launch. Falls back to whatever the
+ * OS gives us when the preferred port is taken (and the registration is then
+ * re-done, see `PhenomenalOAuthProvider`).
+ */
+export declare function preferredLoopbackPort(serverUrl: string): number;
+export declare function loopbackRedirectUrl(port: number): string;
+/**
+ * Binds 127.0.0.1 — never 0.0.0.0. The authorization code arrives in this URL,
+ * and a listener on a routable interface would hand it to the local network.
+ */
+export declare function startLoopback(preferredPort?: number): Promise<LoopbackListener>;
+export interface ProviderOptions {
+    serverUrl: string;
+    redirectUrl: string;
+    home?: string;
+    openBrowser?: (url: URL) => Promise<unknown>;
+    log?: (line: string) => void;
+}
+/**
+ * The SDK's `OAuthClientProvider`, backed by `~/.phenomenal/mcp/<host>.json`.
+ */
+export declare class PhenomenalOAuthProvider implements OAuthClientProvider {
+    private readonly serverUrl;
+    private readonly home;
+    private readonly redirect;
+    private readonly openBrowser;
+    private readonly log;
+    private issuedState;
+    constructor(options: ProviderOptions);
+    private session;
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    /** The state we last handed the authorization server, for the callback check. */
+    get lastIssuedState(): string | undefined;
+    state(): string;
+    clientInformation(): OAuthClientInformationMixed | undefined;
+    saveClientInformation(clientInformation: OAuthClientInformationMixed): void;
+    tokens(): OAuthTokens | undefined;
+    saveTokens(tokens: OAuthTokens): void;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): void;
+    codeVerifier(): string;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): void;
+}
+export interface EnsureAuthorizedOptions {
+    home?: string;
+    openBrowser?: (url: URL) => Promise<unknown>;
+    log?: (line: string) => void;
+    now?: () => number;
+}
+/**
+ * Returns a provider holding a usable access token, opening a browser only if
+ * it has to. The loopback port is bound for the length of the sign-in and
+ * closed before the pump starts — a bridge that idles with an open listener is
+ * a bridge with an open listener all day.
+ */
+export declare function ensureAuthorized(serverUrl: string, options?: EnsureAuthorizedOptions): Promise<PhenomenalOAuthProvider>;

package/dist/auth.js

@@ -0,0 +1,274 @@
+// Browser sign-in for the bridge: dynamic client registration, PKCE, and a
+// loopback listener on 127.0.0.1 that catches the redirect. There is no key to
+// paste and nothing for a customer to configure — they click "Allow" in
+// Phenomenal and the bridge holds the grant from then on.
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import open from 'open';
+import { auth } from '@modelcontextprotocol/sdk/client/auth.js';
+import { expiryFromTokens, readSession, tokensAreFresh, updateSession, } from './store.js';
+/**
+ * What the consent screen shows the person approving this bridge, and what
+ * Settings → Connected agents lists it as. Customer-facing, so it is the
+ * product name — not an implementation label (Bob's call, #2523).
+ */
+export const CLIENT_NAME = 'Phenomenal MCP';
+export const CLIENT_URI = 'https://phenomenal.org';
+/**
+ * A stable port per server, so the registered `redirect_uris` survive between
+ * runs — a fresh ephemeral port every time would invalidate the registration
+ * and force a new consent screen on every launch. Falls back to whatever the
+ * OS gives us when the preferred port is taken (and the registration is then
+ * re-done, see `PhenomenalOAuthProvider`).
+ */
+export function preferredLoopbackPort(serverUrl) {
+    let hash = 2166136261;
+    for (const ch of new URL(serverUrl).origin) {
+        hash ^= ch.charCodeAt(0);
+        hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return 33200 + (hash % 100);
+}
+export function loopbackRedirectUrl(port) {
+    return `http://127.0.0.1:${port}/callback`;
+}
+const DONE_PAGE = (heading, detail) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Phenomenal</title>` +
+    `<style>body{font-family:ui-sans-serif,system-ui,sans-serif;background:#0b0b12;color:#fff;` +
+    `display:grid;place-items:center;height:100vh;margin:0}main{text-align:center;max-width:32rem}` +
+    `h1{color:#b6f441;font-size:1.5rem}p{color:#cfcfd8}</style></head>` +
+    `<body><main><h1>${heading}</h1><p>${detail}</p></main></body></html>`;
+/**
+ * Binds 127.0.0.1 — never 0.0.0.0. The authorization code arrives in this URL,
+ * and a listener on a routable interface would hand it to the local network.
+ */
+export async function startLoopback(preferredPort = 0) {
+    let settle;
+    let fail;
+    let received;
+    let failure;
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== '/callback') {
+            res.writeHead(404, { 'content-type': 'text/plain' }).end('Not found');
+            return;
+        }
+        const error = url.searchParams.get('error');
+        if (error) {
+            const description = url.searchParams.get('error_description') ?? error;
+            res
+                .writeHead(400, { 'content-type': 'text/html; charset=utf-8' })
+                .end(DONE_PAGE('Sign-in was not completed', escapeHtml(description)));
+            const err = new Error(`Phenomenal sign-in failed: ${description}`);
+            failure = err;
+            fail?.(err);
+            return;
+        }
+        const code = url.searchParams.get('code');
+        if (!code) {
+            res.writeHead(400, { 'content-type': 'text/plain' }).end('Missing code');
+            return;
+        }
+        res
+            .writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+            .end(DONE_PAGE('You are connected to Phenomenal', 'You can close this tab and go back to your assistant.'));
+        received = { code, state: url.searchParams.get('state') ?? undefined };
+        settle?.(received);
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            if (preferredPort !== 0 && (error.code === 'EADDRINUSE' || error.code === 'EACCES')) {
+                // Something else holds our stable port; take any port and re-register.
+                server.listen(0, '127.0.0.1');
+                return;
+            }
+            reject(error);
+        };
+        server.on('error', onError);
+        server.once('listening', () => {
+            server.off('error', onError);
+            server.on('error', () => { });
+            resolve();
+        });
+        server.listen(preferredPort, '127.0.0.1');
+    });
+    const port = server.address().port;
+    return {
+        port,
+        redirectUrl: loopbackRedirectUrl(port),
+        waitForCallback: () => new Promise((resolve, reject) => {
+            if (received)
+                return resolve(received);
+            if (failure)
+                return reject(failure);
+            settle = resolve;
+            fail = reject;
+        }),
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}
+/**
+ * The SDK's `OAuthClientProvider`, backed by `~/.phenomenal/mcp/<host>.json`.
+ */
+export class PhenomenalOAuthProvider {
+    serverUrl;
+    home;
+    redirect;
+    openBrowser;
+    log;
+    issuedState;
+    constructor(options) {
+        this.serverUrl = options.serverUrl;
+        this.home = options.home;
+        this.redirect = options.redirectUrl;
+        this.openBrowser = options.openBrowser ?? ((url) => open(url.toString()));
+        this.log = options.log ?? (() => { });
+        // A registration issued for a different loopback port cannot be used: the
+        // authorization request's redirect_uri would not match what was
+        // registered. Drop it and let the SDK register again.
+        const stored = readSession(this.serverUrl, this.home);
+        if (stored?.clientInformation &&
+            !stored.clientInformation.redirect_uris.includes(this.redirect)) {
+            updateSession(this.serverUrl, { clientInformation: undefined, codeVerifier: undefined, redirectPort: undefined }, this.home);
+        }
+    }
+    session() {
+        return readSession(this.serverUrl, this.home) ?? { serverUrl: this.serverUrl };
+    }
+    get redirectUrl() {
+        return this.redirect;
+    }
+    get clientMetadata() {
+        return {
+            client_name: CLIENT_NAME,
+            client_uri: CLIENT_URI,
+            redirect_uris: [this.redirect],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            // A CLI on a customer's laptop cannot keep a secret, so it registers as
+            // a public client and leans on PKCE.
+            token_endpoint_auth_method: 'none',
+        };
+    }
+    /** The state we last handed the authorization server, for the callback check. */
+    get lastIssuedState() {
+        return this.issuedState;
+    }
+    state() {
+        this.issuedState = randomBytes(16).toString('hex');
+        return this.issuedState;
+    }
+    clientInformation() {
+        return this.session().clientInformation;
+    }
+    saveClientInformation(clientInformation) {
+        const full = clientInformation;
+        updateSession(this.serverUrl, { clientInformation: full, redirectPort: portOf(this.redirect) }, this.home);
+    }
+    tokens() {
+        return this.session().tokens;
+    }
+    saveTokens(tokens) {
+        updateSession(this.serverUrl, 
+        // The verifier is single-use; keeping it around only widens the window
+        // in which a stolen store file is worth something.
+        { tokens, expiresAt: expiryFromTokens(tokens), codeVerifier: undefined }, this.home);
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        this.log(`Opening your browser to sign in to Phenomenal…`);
+        this.log(`If it does not open, visit: ${authorizationUrl.toString()}`);
+        try {
+            await this.openBrowser(authorizationUrl);
+        }
+        catch (error) {
+            this.log(`Could not open a browser automatically (${describe(error)}). Use the link above.`);
+        }
+    }
+    saveCodeVerifier(codeVerifier) {
+        updateSession(this.serverUrl, { codeVerifier }, this.home);
+    }
+    codeVerifier() {
+        const verifier = this.session().codeVerifier;
+        if (!verifier) {
+            throw new Error('No PKCE code verifier is saved — start the sign-in again.');
+        }
+        return verifier;
+    }
+    invalidateCredentials(scope) {
+        const patch = scope === 'all'
+            ? {
+                clientInformation: undefined,
+                tokens: undefined,
+                codeVerifier: undefined,
+                expiresAt: undefined,
+            }
+            : scope === 'client'
+                ? { clientInformation: undefined }
+                : scope === 'tokens'
+                    ? { tokens: undefined, expiresAt: undefined }
+                    : scope === 'verifier'
+                        ? { codeVerifier: undefined }
+                        : {};
+        updateSession(this.serverUrl, patch, this.home);
+    }
+}
+/**
+ * Returns a provider holding a usable access token, opening a browser only if
+ * it has to. The loopback port is bound for the length of the sign-in and
+ * closed before the pump starts — a bridge that idles with an open listener is
+ * a bridge with an open listener all day.
+ */
+export async function ensureAuthorized(serverUrl, options = {}) {
+    const { home, openBrowser, log = () => { } } = options;
+    const stored = readSession(serverUrl, home);
+    if (tokensAreFresh(stored, options.now?.() ?? Date.now())) {
+        return new PhenomenalOAuthProvider({
+            serverUrl,
+            // Reuse the registration's own redirect so a still-valid registration is
+            // not thrown away just because we did not bind a port this run.
+            redirectUrl: stored?.clientInformation?.redirect_uris[0] ??
+                loopbackRedirectUrl(stored?.redirectPort ?? preferredLoopbackPort(serverUrl)),
+            home,
+            openBrowser,
+            log,
+        });
+    }
+    const loopback = await startLoopback(stored?.redirectPort ?? preferredLoopbackPort(serverUrl));
+    try {
+        const provider = new PhenomenalOAuthProvider({
+            serverUrl,
+            redirectUrl: loopback.redirectUrl,
+            home,
+            openBrowser,
+            log,
+        });
+        const result = await auth(provider, { serverUrl });
+        if (result === 'AUTHORIZED')
+            return provider;
+        const callback = await loopback.waitForCallback();
+        if (provider.lastIssuedState && callback.state !== provider.lastIssuedState) {
+            throw new Error('The sign-in response did not match the request that started it.');
+        }
+        const finished = await auth(provider, { serverUrl, authorizationCode: callback.code });
+        if (finished !== 'AUTHORIZED') {
+            throw new Error('Phenomenal sign-in did not complete.');
+        }
+        log('Signed in to Phenomenal.');
+        return provider;
+    }
+    finally {
+        await loopback.close();
+    }
+}
+function portOf(redirectUrl) {
+    const port = Number(new URL(redirectUrl).port);
+    return Number.isFinite(port) && port > 0 ? port : undefined;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export interface BridgeOptions {
+    /** Where diagnostics go. stdout is the protocol, so this must not be it. */
+    log?: (line: string) => void;
+}
+export interface BridgeHandle {
+    /** Resolves once both transports are closed. */
+    readonly done: Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Wires two transports together and starts them. The remote starts first: the
+ * local (stdio) transport begins reading stdin the moment it starts, and a
+ * message read before the remote is up would have nowhere to go.
+ */
+export declare function startBridge(local: Transport, remote: Transport, options?: BridgeOptions): Promise<BridgeHandle>;

package/dist/bridge.js

@@ -0,0 +1,57 @@
+/**
+ * The one thing a raw pump has to do that a `Client` would have done for it:
+ * the Protocol class calls `setProtocolVersion` when the initialize result
+ * arrives, and the Streamable HTTP transport sends that value as the
+ * `MCP-Protocol-Version` header on every later request. With nobody in the
+ * middle, the pump has to read it off the wire.
+ */
+function negotiatedProtocolVersion(message) {
+    if (!('result' in message) || typeof message.result !== 'object' || message.result === null) {
+        return undefined;
+    }
+    const version = message.result.protocolVersion;
+    return typeof version === 'string' ? version : undefined;
+}
+/**
+ * Wires two transports together and starts them. The remote starts first: the
+ * local (stdio) transport begins reading stdin the moment it starts, and a
+ * message read before the remote is up would have nowhere to go.
+ */
+export async function startBridge(local, remote, options = {}) {
+    const log = options.log ?? (() => { });
+    let shuttingDown = false;
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        void Promise.allSettled([local.close(), remote.close()]).then(() => resolveDone());
+    };
+    const forward = (to, label) => (message) => {
+        to.send(message).catch((error) => {
+            log(`failed to forward a message ${label}: ${describe(error)}`);
+            shutdown();
+        });
+    };
+    local.onmessage = forward(remote, 'to the Phenomenal server');
+    remote.onmessage = (message) => {
+        const version = negotiatedProtocolVersion(message);
+        if (version)
+            remote.setProtocolVersion?.(version);
+        forward(local, 'to the MCP client')(message);
+    };
+    // An error is not necessarily fatal (the SDK says so explicitly); a close is.
+    local.onerror = (error) => log(`MCP client transport error: ${describe(error)}`);
+    remote.onerror = (error) => log(`Phenomenal server transport error: ${describe(error)}`);
+    local.onclose = shutdown;
+    remote.onclose = shutdown;
+    await remote.start();
+    await local.start();
+    return { done, close: async () => (shutdown(), done) };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+export declare const DEFAULT_SERVER_URL = "https://api.phenomenal.org/mcp";
+export interface CliOptions {
+    url: string;
+    logout: boolean;
+    version: boolean;
+    help: boolean;
+}
+export declare class CliUsageError extends Error {
+}
+/**
+ * `--url <u>`, `--url=<u>` or a bare positional URL; `--logout`, `--version`,
+ * `--help`. Anything else is a usage error rather than a silently ignored
+ * flag — an MCP client config typo should say so, not connect somewhere else.
+ */
+export declare function parseArgs(argv: readonly string[]): CliOptions;
+export declare function usage(version: string): string;
+export interface CliIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+export declare function run(argv: readonly string[], io?: CliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// phenomenal-mcp — the stdio bridge to a Phenomenal MCP server.
+//
+// stdout is the MCP protocol stream. NOTHING may be written there except
+// JSON-RPC: a stray log line corrupts the session and the client reports a
+// parse error it cannot attribute. Diagnostics go to stderr.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ensureAuthorized } from './auth.js';
+import { startBridge } from './bridge.js';
+import { clearSession, storePath } from './store.js';
+import { readPackageVersion } from './version.js';
+export const DEFAULT_SERVER_URL = 'https://api.phenomenal.org/mcp';
+export class CliUsageError extends Error {
+}
+/**
+ * `--url <u>`, `--url=<u>` or a bare positional URL; `--logout`, `--version`,
+ * `--help`. Anything else is a usage error rather than a silently ignored
+ * flag — an MCP client config typo should say so, not connect somewhere else.
+ */
+export function parseArgs(argv) {
+    const options = {
+        url: DEFAULT_SERVER_URL,
+        logout: false,
+        version: false,
+        help: false,
+    };
+    let urlSeen = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--logout') {
+            options.logout = true;
+        }
+        else if (arg === '--version' || arg === '-v') {
+            options.version = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            options.help = true;
+        }
+        else if (arg === '--url') {
+            const value = argv[i + 1];
+            if (!value || value.startsWith('-'))
+                throw new CliUsageError('--url needs a URL');
+            options.url = validUrl(value);
+            urlSeen = true;
+            i += 1;
+        }
+        else if (arg.startsWith('--url=')) {
+            options.url = validUrl(arg.slice('--url='.length));
+            urlSeen = true;
+        }
+        else if (!arg.startsWith('-') && !urlSeen) {
+            options.url = validUrl(arg);
+            urlSeen = true;
+        }
+        else {
+            throw new CliUsageError(`unknown argument: ${arg}`);
+        }
+    }
+    return options;
+}
+function validUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new CliUsageError(`not a URL: ${value}`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new CliUsageError(`the server URL must be http(s): ${value}`);
+    }
+    return parsed.toString();
+}
+export function usage(version) {
+    return [
+        `phenomenal-mcp ${version} — connect an MCP client to Phenomenal over stdio.`,
+        '',
+        'Usage:',
+        '  npx @phenomenalorg/mcp [<url>] [--url <url>] [--logout] [--version]',
+        '',
+        'Options:',
+        `  --url <url>   The Phenomenal MCP endpoint (default ${DEFAULT_SERVER_URL})`,
+        '  --logout      Forget the saved sign-in for that server and exit',
+        '  --version     Print the version and exit',
+        '  --help        Print this and exit',
+        '',
+        'Most clients no longer need this bridge — Claude Code, Codex and Claude',
+        'Desktop can talk to Phenomenal directly over HTTP. Use it when your client',
+        'only speaks stdio.',
+    ].join('\n');
+}
+const defaultIo = {
+    out: (line) => process.stdout.write(`${line}\n`),
+    err: (line) => process.stderr.write(`phenomenal-mcp: ${line}\n`),
+};
+export async function run(argv, io = defaultIo) {
+    const version = readPackageVersion();
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        io.err(error instanceof CliUsageError ? error.message : String(error));
+        io.err('Try --help.');
+        return 2;
+    }
+    if (options.help) {
+        io.out(usage(version));
+        return 0;
+    }
+    if (options.version) {
+        io.out(version);
+        return 0;
+    }
+    if (options.logout) {
+        const had = clearSession(options.url);
+        io.err(had
+            ? `Signed out of ${options.url}. Removed ${storePath(options.url)}.`
+            : `No saved sign-in for ${options.url}.`);
+        return 0;
+    }
+    const provider = await ensureAuthorized(options.url, { log: io.err });
+    const remote = new StreamableHTTPClientTransport(new URL(options.url), {
+        authProvider: provider,
+    });
+    const local = new StdioServerTransport();
+    io.err(`Connected to ${options.url}.`);
+    const handle = await startBridge(local, remote, { log: io.err });
+    await handle.done;
+    return 0;
+}
+// `import.meta.url` is the built dist/cli.js when npm runs the bin; the guard
+// keeps `run` importable from tests without starting a session.
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url.endsWith('/cli.js');
+if (invokedDirectly) {
+    run(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        process.stderr.write(`phenomenal-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { startBridge, type BridgeHandle, type BridgeOptions } from './bridge.js';
+export { CLIENT_NAME, CLIENT_URI, ensureAuthorized, loopbackRedirectUrl, PhenomenalOAuthProvider, preferredLoopbackPort, startLoopback, type LoopbackListener, } from './auth.js';
+export { clearSession, readSession, storePath, storeRoot, tokensAreFresh, type StoredSession, } from './store.js';
+export { DEFAULT_SERVER_URL, parseArgs, run, usage, type CliOptions } from './cli.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { startBridge } from './bridge.js';
+export { CLIENT_NAME, CLIENT_URI, ensureAuthorized, loopbackRedirectUrl, PhenomenalOAuthProvider, preferredLoopbackPort, startLoopback, } from './auth.js';
+export { clearSession, readSession, storePath, storeRoot, tokensAreFresh, } from './store.js';
+export { DEFAULT_SERVER_URL, parseArgs, run, usage } from './cli.js';

package/dist/store.d.ts

@@ -0,0 +1,40 @@
+import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+/** Everything the bridge remembers about one Phenomenal MCP server. */
+export interface StoredSession {
+    /** The `/mcp` URL these credentials belong to. */
+    serverUrl: string;
+    /** The loopback port the registration's `redirect_uris` were issued for. */
+    redirectPort?: number;
+    clientInformation?: OAuthClientInformationFull;
+    tokens?: OAuthTokens;
+    /** In-flight PKCE verifier; only meaningful between redirect and callback. */
+    codeVerifier?: string;
+    /** Epoch ms at which `tokens.access_token` expires, if the server said. */
+    expiresAt?: number;
+}
+export declare const STORE_DIR_MODE = 448;
+export declare const STORE_FILE_MODE = 384;
+/** Refresh this long before the declared expiry rather than racing it. */
+export declare const EXPIRY_SKEW_MS = 60000;
+export declare function storeRoot(home?: string): string;
+/**
+ * One file per server. Host and path both matter (two servers can share a
+ * host), and every character outside a conservative allowlist is replaced —
+ * so no input can walk out of the store directory.
+ */
+export declare function storeFileName(serverUrl: string): string;
+export declare function storePath(serverUrl: string, home?: string): string;
+export declare function readSession(serverUrl: string, home?: string): StoredSession | undefined;
+export declare function writeSession(serverUrl: string, session: StoredSession, home?: string): void;
+/** Merge a patch into the stored session. Returns the session as written. */
+export declare function updateSession(serverUrl: string, patch: Partial<StoredSession>, home?: string): StoredSession;
+/** `--logout`. Returns whether there was anything to delete. */
+export declare function clearSession(serverUrl: string, home?: string): boolean;
+/**
+ * Whether the stored access token can be used without talking to the
+ * authorization server first. An absent `expiresAt` means the server declared
+ * no expiry — the token is good until it is refused.
+ */
+export declare function tokensAreFresh(session: StoredSession | undefined, now?: number): boolean;
+/** Epoch ms for a token response's `expires_in`, or undefined if it had none. */
+export declare function expiryFromTokens(tokens: OAuthTokens, now?: number): number | undefined;

package/dist/store.js

@@ -0,0 +1,87 @@
+// The on-disk half of the bridge: one file per Phenomenal server, holding the
+// dynamic client registration and the OAuth tokens obtained for it.
+//
+// These are a person's credentials for their school's data, sitting in a
+// customer's home directory, so the file is written 0600 and its directory
+// 0700 — and both are re-tightened on every write, because `writeFileSync`'s
+// `mode` applies only when it CREATES the file. A file that was once written
+// world-readable stays world-readable otherwise.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const STORE_DIR_MODE = 0o700;
+export const STORE_FILE_MODE = 0o600;
+/** Refresh this long before the declared expiry rather than racing it. */
+export const EXPIRY_SKEW_MS = 60_000;
+export function storeRoot(home = homedir()) {
+    return join(home, '.phenomenal', 'mcp');
+}
+/**
+ * One file per server. Host and path both matter (two servers can share a
+ * host), and every character outside a conservative allowlist is replaced —
+ * so no input can walk out of the store directory.
+ */
+export function storeFileName(serverUrl) {
+    const url = new URL(serverUrl);
+    const path = url.pathname.replace(/\/+$/, '');
+    const key = `${url.host}${path}`.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return `${key}.json`;
+}
+export function storePath(serverUrl, home = homedir()) {
+    return join(storeRoot(home), storeFileName(serverUrl));
+}
+export function readSession(serverUrl, home) {
+    const path = storePath(serverUrl, home);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // A corrupt file is indistinguishable from no file for our purposes: the
+        // next sign-in overwrites it. Failing here would strand the customer.
+        return undefined;
+    }
+}
+export function writeSession(serverUrl, session, home) {
+    const dir = storeRoot(home);
+    mkdirSync(dir, { recursive: true, mode: STORE_DIR_MODE });
+    chmodSync(dir, STORE_DIR_MODE);
+    const path = storePath(serverUrl, home);
+    writeFileSync(path, `${JSON.stringify(session, null, 2)}\n`, { mode: STORE_FILE_MODE });
+    chmodSync(path, STORE_FILE_MODE);
+}
+/** Merge a patch into the stored session. Returns the session as written. */
+export function updateSession(serverUrl, patch, home) {
+    const next = {
+        ...(readSession(serverUrl, home) ?? { serverUrl }),
+        ...patch,
+        serverUrl,
+    };
+    writeSession(serverUrl, next, home);
+    return next;
+}
+/** `--logout`. Returns whether there was anything to delete. */
+export function clearSession(serverUrl, home) {
+    const path = storePath(serverUrl, home);
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+/**
+ * Whether the stored access token can be used without talking to the
+ * authorization server first. An absent `expiresAt` means the server declared
+ * no expiry — the token is good until it is refused.
+ */
+export function tokensAreFresh(session, now = Date.now()) {
+    if (!session?.tokens?.access_token)
+        return false;
+    if (session.expiresAt === undefined)
+        return true;
+    return session.expiresAt - now > EXPIRY_SKEW_MS;
+}
+/** Epoch ms for a token response's `expires_in`, or undefined if it had none. */
+export function expiryFromTokens(tokens, now = Date.now()) {
+    return typeof tokens.expires_in === 'number' ? now + tokens.expires_in * 1000 : undefined;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The published version, read from the package manifest beside `dist/`. */
+export declare function readPackageVersion(): string;

package/dist/version.js

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module';
+/** The published version, read from the package manifest beside `dist/`. */
+export function readPackageVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../package.json');
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@phenomenalorg/mcp",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Phenomenal MCP bridge — connects a stdio-only MCP client to the Phenomenal MCP server over Streamable HTTP, with browser sign-in.",
+  "license": "MIT",
+  "homepage": "https://phenomenal.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PTO-pro/ptopro.git",
+    "directory": "packages/phenomenal-mcp"
+  },
+  "keywords": [
+    "phenomenal",
+    "mcp",
+    "modelcontextprotocol",
+    "stdio",
+    "bridge"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "phenomenal-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}