@a-venue/guideon-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @a-venue/guideon-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.
+Connect Claude, Cursor, Codex and other AI agents to [GuideOn](https://guideon.loretia.com). It is a small
+bridge: your agent talks to it over stdio, and it talks to GuideOn's remote MCP server, signing you in
+through your browser the first time. The agent acts **as you**: it sees your organizations and can change
+what your role allows.
+
+## Use it
+
+Claude Code:
+
+```bash
+claude mcp add guideon -- npx -y @a-venue/guideon-mcp
+```
+
+Anything else (Cursor, Claude Desktop, Codex, VS Code), in its MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "guideon": { "command": "npx", "args": ["-y", "@a-venue/guideon-mcp"] }
+  }
+}
+```
+
+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://guideon.askn.us/api/mcp` |
+| `--token` | `GUIDEON_MCP_TOKEN` | the cached sign-in |
+
+Logs go to stderr; stdout carries the protocol.
+
+## Tools
+
+`list_organizations`, `list_venues`, `get_venue`, `update_venue`, `list_pois`, `create_poi`, `update_poi`,
+`list_avatars`, `list_experiences`, `list_content_items`, `search_knowledge`, `reindex_knowledge`.

package/dist/auth.js

@@ -0,0 +1,211 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { exec } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+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');
+const tokenFile = () => join(configDir(), 'mcp-token.json');
+function readTokens() {
+    try {
+        return existsSync(tokenFile())
+            ? JSON.parse(readFileSync(tokenFile(), 'utf8'))
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The cached token for this server, unless it has expired. */
+export function storedToken(url, now = Date.now()) {
+    const entry = readTokens()[url];
+    return entry && (!entry.expiresAt || entry.expiresAt > now)
+        ? entry.accessToken
+        : null;
+}
+export function saveToken(url, accessToken, expiresInSeconds) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(tokenFile(), JSON.stringify({
+        ...readTokens(),
+        [url]: {
+            accessToken,
+            expiresAt: expiresInSeconds
+                ? Date.now() + expiresInSeconds * 1000
+                : undefined,
+        },
+    }, null, 2), { mode: 0o600 });
+    chmodSync(tokenFile(), 0o600);
+}
+export function openBrowser(url) {
+    const command = process.platform === 'darwin'
+        ? `open "${url}"`
+        : process.platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    exec(command, (error) => {
+        if (error) {
+            log(`Open this address in your browser to sign in:\n${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, 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(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') {
+                res.writeHead(404).end();
+                return;
+            }
+            const finish = (status, title, body, outcome) => {
+                res
+                    .writeHead(status, { 'Content-Type': 'text/html' })
+                    .end(page(title, body));
+                clearTimeout(timer);
+                server.close();
+                outcome();
+            };
+            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.')));
+                return;
+            }
+            fetch(endpoints.token, {
+                method: 'POST',
+                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(),
+                    ...(clientId ? { client_id: clientId } : {}),
+                }),
+            })
+                .then(async (response) => {
+                if (!response.ok) {
+                    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,
+                }));
+            })
+                .catch((cause) => finish(500, 'Sign-in did not complete', 'Please try again.', () => reject(cause)));
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new Error('Sign-in timed out after two minutes.'));
+        }, LOGIN_TIMEOUT_MS);
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            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

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.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);
+    const at = args.findIndex((arg) => arg === `--${name}` || arg.startsWith(`--${name}=`));
+    if (at === -1) {
+        return undefined;
+    }
+    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,
+    }));
+    return client;
+}
+const isUnauthorized = (error) => /\b401\b|unauthori[sz]ed/i.test(error instanceof Error ? error.message : String(error));
+async function login(url) {
+    const { accessToken, expiresIn } = await signIn(await discover(url), url);
+    saveToken(url, accessToken, expiresIn);
+    return accessToken;
+}
+async function main() {
+    const url = option('url') ?? process.env.GUIDEON_MCP_URL ?? DEFAULT_URL;
+    const given = option('token') ?? process.env.GUIDEON_MCP_TOKEN;
+    let remote;
+    try {
+        remote = await connect(url, given ?? storedToken(url));
+    }
+    catch (error) {
+        // A token someone handed us is theirs to fix; ours we can renew.
+        if (given || !isUnauthorized(error)) {
+            throw error;
+        }
+        remote = await connect(url, await login(url));
+    }
+    const local = new Server({ name: 'guideon', version: '0.1.0' }, { capabilities: { tools: {} } });
+    local.setRequestHandler(ListToolsRequestSchema, () => remote.listTools());
+    local.setRequestHandler(CallToolRequestSchema, (request) => remote.callTool(request.params));
+    await local.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error('[guideon-mcp]', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@a-venue/guideon-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "model-context-protocol",
+    "guideon",
+    "claude",
+    "cursor",
+    "ai-agent"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "guideon-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/*.test.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "5.9.3",
+    "@guideon/config": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "tsc && node --test dist/*.test.js"
+  }
 }