@a-venue/guideon-mcp 0.1.0 → 0.2.0

package/README.md

@@ -23,14 +23,17 @@ Anything else (Cursor, Claude Desktop, Codex, VS Code), in its MCP settings:
 }
 ```
 
-The first run opens your browser; sign in to GuideOn and choose **Allow access**. The token is kept in
+The first run opens your browser; sign in to GuideOn and choose **Allow access**. The bridge finds the sign-in
+itself (OAuth discovery and dynamic client registration), so it works with any MCP server that follows the
+same rules. An agent that can connect to a server by address needs no bridge:
+`claude mcp add --transport http guideon https://guideon.askn.us/api/mcp`. The token is kept in
 `~/.guideon/mcp-token.json` (readable by you only) and lasts seven days.
 
 ## Options
 
 | Flag | Environment variable | Default |
 | --- | --- | --- |
-| `--url` | `GUIDEON_MCP_URL` | `https://api.guideon.loretia.com/api/mcp` |
+| `--url` | `GUIDEON_MCP_URL` | `https://guideon.askn.us/api/mcp` |
 | `--token` | `GUIDEON_MCP_TOKEN` | the cached sign-in |
 
 Logs go to stderr; stdout carries the protocol.

package/dist/auth.js

@@ -4,7 +4,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from '
 import { createServer } from 'node:http';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-export const DEFAULT_URL = 'https://api.guideon.loretia.com/api/mcp';
+export const DEFAULT_URL = 'https://guideon.askn.us/api/mcp';
 const LOGIN_TIMEOUT_MS = 120_000;
 const log = (message) => console.error(`[guideon-mcp] ${message}`);
 const configDir = () => process.env.GUIDEON_MCP_HOME ?? join(homedir(), '.guideon');
@@ -32,7 +32,9 @@ export function saveToken(url, accessToken, expiresInSeconds) {
         ...readTokens(),
         [url]: {
             accessToken,
-            expiresAt: expiresInSeconds ? Date.now() + expiresInSeconds * 1000 : undefined,
+            expiresAt: expiresInSeconds
+                ? Date.now() + expiresInSeconds * 1000
+                : undefined,
         },
     }, null, 2), { mode: 0o600 });
     chmodSync(tokenFile(), 0o600);
@@ -51,16 +53,70 @@ export function openBrowser(url) {
 }
 const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 const page = (title, body) => `<!doctype html><meta charset="utf-8"><title>GuideOn</title><body style="font-family:system-ui;text-align:center;padding:64px"><h2>${escapeHtml(title)}</h2><p>${escapeHtml(body)}</p></body>`;
+const getJson = async (url) => {
+    const response = await fetch(url, {
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`${url} answered ${response.status}.`);
+    }
+    return (await response.json());
+};
+/**
+ * Finds the sign-in endpoints the way MCP's OAuth says to: an unauthenticated request is
+ * answered 401 with the address of the resource metadata (RFC 9728), that names the
+ * authorization server, and its metadata (RFC 8414) lists the endpoints. Works against any
+ * server that follows the same rules, not only GuideOn.
+ */
+export async function discover(mcpUrl) {
+    const target = new URL(mcpUrl);
+    const probe = await fetch(mcpUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 0,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-03-26',
+                capabilities: {},
+                clientInfo: { name: 'guideon-mcp', version: '0' },
+            },
+        }),
+    });
+    const advertised = /resource_metadata="([^"]+)"/.exec(probe.headers.get('www-authenticate') ?? '')?.[1];
+    const resource = await getJson(advertised ??
+        `${target.origin}/.well-known/oauth-protected-resource${target.pathname}`);
+    const issuer = resource.authorization_servers?.[0];
+    if (!issuer) {
+        throw new Error(`${mcpUrl} does not say where to sign in.`);
+    }
+    const at = new URL(issuer);
+    const server = await getJson(`${at.origin}/.well-known/oauth-authorization-server${at.pathname === '/' ? '' : at.pathname}`);
+    if (!server.authorization_endpoint || !server.token_endpoint) {
+        throw new Error(`${issuer} is missing its sign-in endpoints.`);
+    }
+    return {
+        authorization: server.authorization_endpoint,
+        token: server.token_endpoint,
+        registration: server.registration_endpoint,
+    };
+}
 /**
  * Sign-in by the browser, OAuth authorization-code flow with PKCE: a one-shot server on a
- * random local port catches the redirect, the code is traded for a token at `tokenUrl`.
- * `open` is injectable so a test can play the browser.
+ * random local port catches the redirect, registers itself as a client there (RFC 7591), and
+ * trades the code for a token. `open` is injectable so a test can play the browser.
  */
-export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
+export function signIn(endpoints, resource, open = openBrowser) {
     const verifier = randomBytes(32).toString('base64url');
     const challenge = createHash('sha256').update(verifier).digest('base64url');
     const state = randomBytes(16).toString('hex');
+    let clientId;
     return new Promise((resolve, reject) => {
+        const redirectUri = () => `http://127.0.0.1:${server.address().port}/callback`;
         const server = createServer((req, res) => {
             const url = new URL(req.url ?? '/', 'http://127.0.0.1');
             if (url.pathname !== '/callback') {
@@ -68,7 +124,9 @@ export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
                 return;
             }
             const finish = (status, title, body, outcome) => {
-                res.writeHead(status, { 'Content-Type': 'text/html' }).end(page(title, body));
+                res
+                    .writeHead(status, { 'Content-Type': 'text/html' })
+                    .end(page(title, body));
                 clearTimeout(timer);
                 server.close();
                 outcome();
@@ -76,18 +134,23 @@ export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
             const code = url.searchParams.get('code');
             const error = url.searchParams.get('error');
             if (error || !code || url.searchParams.get('state') !== state) {
-                finish(400, 'Sign-in did not complete', error ?? 'Please try again.', () => reject(new Error(error ? `Sign-in refused: ${error}` : 'Sign-in callback was invalid.')));
+                finish(400, 'Sign-in did not complete', error ?? 'Please try again.', () => reject(new Error(error
+                    ? `Sign-in refused: ${error}`
+                    : 'Sign-in callback was invalid.')));
                 return;
             }
-            const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
-            fetch(tokenUrl, {
+            fetch(endpoints.token, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                },
+                body: new URLSearchParams({
                     grant_type: 'authorization_code',
                     code,
                     code_verifier: verifier,
-                    redirect_uri: redirectUri,
+                    redirect_uri: redirectUri(),
+                    ...(clientId ? { client_id: clientId } : {}),
                 }),
             })
                 .then(async (response) => {
@@ -95,7 +158,10 @@ export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
                     throw new Error(`Token exchange failed (${response.status}): ${await response.text()}`);
                 }
                 const body = (await response.json());
-                finish(200, 'You are signed in', 'You can close this tab and go back to your agent.', () => resolve({ accessToken: body.access_token, expiresIn: body.expires_in }));
+                finish(200, 'You are signed in', 'You can close this tab and go back to your agent.', () => resolve({
+                    accessToken: body.access_token,
+                    expiresIn: body.expires_in,
+                }));
             })
                 .catch((cause) => finish(500, 'Sign-in did not complete', 'Please try again.', () => reject(cause)));
         });
@@ -105,13 +171,41 @@ export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
         }, LOGIN_TIMEOUT_MS);
         server.on('error', reject);
         server.listen(0, '127.0.0.1', () => {
-            const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
-            const target = new URL(authorizeUrl);
-            target.searchParams.set('redirect_uri', redirectUri);
-            target.searchParams.set('code_challenge', challenge);
-            target.searchParams.set('state', state);
-            log('Opening your browser to sign in to GuideOn...');
-            open(target.toString());
+            void (async () => {
+                if (endpoints.registration) {
+                    const response = await fetch(endpoints.registration, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({
+                            client_name: 'guideon-mcp on your computer',
+                            redirect_uris: [redirectUri()],
+                        }),
+                    });
+                    if (!response.ok) {
+                        throw new Error(`Registering this client failed (${response.status}).`);
+                    }
+                    clientId = (await response.json())
+                        .client_id;
+                }
+                const target = new URL(endpoints.authorization);
+                for (const [key, value] of Object.entries({
+                    ...(clientId ? { client_id: clientId } : {}),
+                    response_type: 'code',
+                    redirect_uri: redirectUri(),
+                    code_challenge: challenge,
+                    code_challenge_method: 'S256',
+                    state,
+                    resource,
+                })) {
+                    target.searchParams.set(key, value);
+                }
+                log('Opening your browser to sign in to GuideOn...');
+                open(target.toString());
+            })().catch((cause) => {
+                clearTimeout(timer);
+                server.close();
+                reject(cause instanceof Error ? cause : new Error(String(cause)));
+            });
         });
     });
 }

package/dist/cli.js

@@ -4,7 +4,7 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { DEFAULT_URL, saveToken, signIn, storedToken } from './auth.js';
+import { DEFAULT_URL, discover, saveToken, signIn, storedToken, } from './auth.js';
 // stdout is the protocol; everything a person should read goes to stderr.
 function option(name) {
     const args = process.argv.slice(2);
@@ -12,22 +12,22 @@ function option(name) {
     if (at === -1) {
         return undefined;
     }
-    return args[at].includes('=') ? args[at].split('=').slice(1).join('=') : args[at + 1];
+    return args[at].includes('=')
+        ? args[at].split('=').slice(1).join('=')
+        : args[at + 1];
 }
 async function connect(url, token) {
     const client = new Client({ name: 'guideon-mcp', version: '0.1.0' });
     await client.connect(new StreamableHTTPClientTransport(new URL(url), {
-        requestInit: token ? { headers: { Authorization: `Bearer ${token}` } } : undefined,
+        requestInit: token
+            ? { headers: { Authorization: `Bearer ${token}` } }
+            : undefined,
     }));
     return client;
 }
 const isUnauthorized = (error) => /\b401\b|unauthori[sz]ed/i.test(error instanceof Error ? error.message : String(error));
 async function login(url) {
-    const info = (await (await fetch(url)).json());
-    if (!info.authorization_endpoint) {
-        throw new Error(`${url} is not a GuideOn MCP server.`);
-    }
-    const { accessToken, expiresIn } = await signIn(info.authorization_endpoint, `${url.replace(/\/$/, '')}/oauth/token`);
+    const { accessToken, expiresIn } = await signIn(await discover(url), url);
     saveToken(url, accessToken, expiresIn);
     return accessToken;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-venue/guideon-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Connect Claude, Cursor, Codex and other AI agents to GuideOn: a stdio bridge to GuideOn's remote MCP server, with browser sign-in.",
   "keywords": [
     "mcp",