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

package/README.md

@@ -1,3 +1,41 @@
-# 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 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` |
+| `--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,117 @@
+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://api.guideon.loretia.com/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>`;
+/**
+ * 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.
+ */
+export function signIn(authorizeUrl, tokenUrl, open = openBrowser) {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    const state = randomBytes(16).toString('hex');
+    return new Promise((resolve, reject) => {
+        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;
+            }
+            const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
+            fetch(tokenUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    grant_type: 'authorization_code',
+                    code,
+                    code_verifier: verifier,
+                    redirect_uri: redirectUri,
+                }),
+            })
+                .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', () => {
+            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());
+        });
+    });
+}

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, 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 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`);
+    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.1.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"
+  }
 }