@gpsglobal-ai/gpsglobal 1.4.1

package/dist/config/env.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const DEFAULT_ENV_PATH = path.join(os.homedir(), '.gps', 'mcp.env');
+export function parseEnvFile(content) {
+    const out = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const exportPrefix = trimmed.startsWith('export ') ? 7 : 0;
+        const body = trimmed.slice(exportPrefix);
+        const eq = body.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = body.slice(0, eq).trim();
+        let value = body.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function loadGpsConfig(envPath = process.env.GPS_MCP_ENV_PATH ?? DEFAULT_ENV_PATH) {
+    const apiBase = process.env.GPS_API_BASE;
+    const accessToken = process.env.GPS_ACCESS_TOKEN;
+    const lpId = process.env.GPS_LP_ID;
+    const role = process.env.GPS_ROLE ?? 'lp';
+    const username = process.env.GPS_USERNAME ?? '';
+    if (apiBase && accessToken && lpId) {
+        return { apiBase: normalizeApiBase(apiBase), accessToken, lpId, role, username };
+    }
+    if (!fs.existsSync(envPath)) {
+        throw new Error(`GPS MCP credentials not found. Run: npx gpsglobal login\nExpected file: ${envPath}`);
+    }
+    const parsed = parseEnvFile(fs.readFileSync(envPath, 'utf8'));
+    const merged = {
+        apiBase: normalizeApiBase(parsed.GPS_API_BASE ?? 'http://localhost:8080'),
+        accessToken: parsed.GPS_ACCESS_TOKEN ?? '',
+        lpId: parsed.GPS_LP_ID ?? '',
+        role: parsed.GPS_ROLE ?? 'lp',
+        username: parsed.GPS_USERNAME ?? '',
+    };
+    if (!merged.accessToken || !merged.lpId) {
+        throw new Error(`Invalid ${envPath} — missing GPS_ACCESS_TOKEN or GPS_LP_ID. Run: npx gpsglobal login --refresh`);
+    }
+    return merged;
+}
+export function normalizeApiBase(base) {
+    return base.replace(/\/+$/, '');
+}
+export function writeGpsEnvFile(config, envPath = DEFAULT_ENV_PATH) {
+    const dir = path.dirname(envPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const lines = [
+        '# GPS MCP credentials — chmod 600 — do not commit',
+        `export GPS_API_BASE=${config.apiBase}`,
+        `export GPS_ACCESS_TOKEN=${config.accessToken}`,
+        `export GPS_LP_ID=${config.lpId}`,
+        `export GPS_ROLE=${config.role}`,
+        `export GPS_USERNAME=${config.username}`,
+        '',
+    ];
+    fs.writeFileSync(envPath, lines.join('\n'), { mode: 0o600 });
+    try {
+        fs.chmodSync(envPath, 0o600);
+    }
+    catch {
+        // Windows may not support chmod
+    }
+}
+export function assertMcpEligibleRole(role) {
+    const r = role.toLowerCase();
+    if (r === 'gp' || r === 'content_manager') {
+        throw new Error('MCP fund wiki tools require an LP account. GP and content_manager roles cannot use these tools.');
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,8 @@
+export interface HttpServerOptions {
+    port: number;
+    host: string;
+    apiBase: string;
+    publicBaseUrl: string;
+    enabled: boolean;
+}
+export declare function startHttpServer(opts: HttpServerOptions): Promise<void>;

package/dist/http.js

@@ -0,0 +1,115 @@
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { GpsApiClient } from './clients/gps-api.js';
+import { assertMcpEligibleRole } from './config/env.js';
+import { createGpsMcpServer } from './server/factory.js';
+import { decodeGpsJwt } from './lib/jwt.js';
+import { assertMcpHttpToken } from './lib/token-policy.js';
+function parseBearer(req) {
+    const h = req.headers.authorization;
+    if (!h?.startsWith('Bearer '))
+        return null;
+    return h.slice(7).trim() || null;
+}
+function configFromToken(token, apiBase) {
+    const claims = decodeGpsJwt(token);
+    return {
+        apiBase,
+        accessToken: token,
+        lpId: claims.lpId ?? '',
+        role: claims.role ?? 'lp',
+        username: claims.sub ?? '',
+    };
+}
+function sendUnauthorized(res, resourceMetadataUrl, message) {
+    res.setHeader('WWW-Authenticate', `Bearer realm="gps-mcp", resource_metadata="${resourceMetadataUrl}"`);
+    res.status(401).json({ error: 'Unauthorized', message });
+}
+export async function startHttpServer(opts) {
+    const app = createMcpExpressApp({ host: opts.host });
+    const resourceMetadataUrl = `${opts.publicBaseUrl}/.well-known/oauth-protected-resource`;
+    const authServer = `${opts.apiBase}/api/v2/oauth/mcp-cli`;
+    app.get('/health', (_req, res) => {
+        if (!opts.enabled) {
+            res.status(503).json({ status: 'disabled', message: 'GPS MCP HTTP is disabled' });
+            return;
+        }
+        res.json({ status: 'ok', service: 'gpsglobal', version: '1.4.0' });
+    });
+    app.get('/.well-known/oauth-protected-resource', (_req, res) => {
+        res.json({
+            resource: `${opts.publicBaseUrl}/mcp`,
+            authorization_servers: [authServer],
+            scopes_supported: ['mcp:read'],
+            bearer_methods_supported: ['header'],
+        });
+    });
+    const handleMcpPost = async (req, res) => {
+        if (!opts.enabled) {
+            res.status(503).json({ error: 'GPS MCP is temporarily disabled' });
+            return;
+        }
+        const token = parseBearer(req);
+        if (!token) {
+            sendUnauthorized(res, resourceMetadataUrl, 'Bearer token required. Run: npx gpsglobal setup');
+            return;
+        }
+        const claims = decodeGpsJwt(token);
+        const config = configFromToken(token, opts.apiBase);
+        const strictAud = process.env.GPS_MCP_STRICT_AUD !== 'false';
+        try {
+            assertMcpHttpToken(claims, { resourceUrl: `${opts.publicBaseUrl}/mcp`, strictAudience: strictAud });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            sendUnauthorized(res, resourceMetadataUrl, msg);
+            return;
+        }
+        if (!config.lpId) {
+            sendUnauthorized(res, resourceMetadataUrl, 'Token missing lpId claim');
+            return;
+        }
+        try {
+            assertMcpEligibleRole(config.role);
+            const client = new GpsApiClient(config);
+            await client.listFunds();
+            const server = createGpsMcpServer(client);
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            res.on('close', () => {
+                void transport.close();
+                void server.close();
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('401') || msg.includes('Authentication')) {
+                sendUnauthorized(res, resourceMetadataUrl, 'Invalid or expired token. Run: npx gpsglobal login --refresh');
+                return;
+            }
+            if (!res.headersSent) {
+                res.status(500).json({ error: 'Internal error', message: msg });
+            }
+        }
+    };
+    app.post('/mcp', async (req, res) => {
+        await handleMcpPost(req, res);
+    });
+    // MCP spec: unauthenticated GET /mcp → 401 + WWW-Authenticate (host OAuth discovery)
+    app.get('/mcp', (req, res) => {
+        if (!opts.enabled) {
+            res.status(503).json({ error: 'GPS MCP is temporarily disabled' });
+            return;
+        }
+        const token = parseBearer(req);
+        if (!token) {
+            sendUnauthorized(res, resourceMetadataUrl, 'Authentication required. Use Cursor Connect or run: npx gpsglobal setup');
+            return;
+        }
+        res.status(405).json({ error: 'Method not allowed — use POST for MCP requests' });
+    });
+    app.listen(opts.port, opts.host, () => {
+        console.error(`[gps-mcp] HTTP http://${opts.host}:${opts.port}/mcp (enabled=${opts.enabled})`);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare function startStdioServer(): Promise<void>;
+export declare function startHttpFromEnv(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,20 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { GpsApiClient } from './clients/gps-api.js';
+import { loadGpsConfig, normalizeApiBase } from './config/env.js';
+import { createGpsMcpServer } from './server/factory.js';
+import { startHttpServer } from './http.js';
+export async function startStdioServer() {
+    const config = loadGpsConfig();
+    const client = new GpsApiClient(config);
+    const server = createGpsMcpServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+export async function startHttpFromEnv() {
+    const port = Number(process.env.PORT ?? 3100);
+    const host = process.env.MCP_HOST ?? '0.0.0.0';
+    const apiBase = normalizeApiBase(process.env.GPS_API_BASE ?? 'http://localhost:8080');
+    const publicBaseUrl = normalizeApiBase(process.env.GPS_MCP_PUBLIC_URL ?? `http://localhost:${port}`);
+    const enabled = process.env.GPS_MCP_ENABLED !== 'false';
+    await startHttpServer({ port, host, apiBase, publicBaseUrl, enabled });
+}

package/dist/lib/cursor-config.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from host-config.js */
+export { PACKAGE, MCP_SERVER_KEY, buildStdioEntry, buildRemoteEntry, buildOAuthConnectEntry, cursorConfigPath, envFilePlaceholder, mergeCursorConfig, resolveMcpPublicUrl, type StdioEntry as CursorMcpEntry, } from './host-config.js';

package/dist/lib/cursor-config.js

@@ -0,0 +1,2 @@
+/** @deprecated Import from host-config.js */
+export { PACKAGE, MCP_SERVER_KEY, buildStdioEntry, buildRemoteEntry, buildOAuthConnectEntry, cursorConfigPath, envFilePlaceholder, mergeCursorConfig, resolveMcpPublicUrl, } from './host-config.js';

package/dist/lib/host-config.d.ts

@@ -0,0 +1,51 @@
+/** npm scoped package under org gpsglobal-ai (see docs/57-mcp/018-npm-publish-and-cicd.md). */
+export declare const NPM_PACKAGE = "@gpsglobal-ai/gpsglobal";
+/** MCP protocol server key in mcp.json — short, stable across hosts. */
+export declare const MCP_SERVER_KEY = "gpsglobal";
+/** CLI binary name after install (`npm i -g` → `gpsglobal` command). */
+export declare const CLI_BIN = "gpsglobal";
+/** @alias NPM_PACKAGE */
+export declare const PACKAGE = "@gpsglobal-ai/gpsglobal";
+export interface StdioEntry {
+    command: string;
+    args: string[];
+    envFile?: string;
+    env?: Record<string, string>;
+}
+export interface RemoteEntry {
+    url: string;
+    headers?: Record<string, string>;
+}
+export type HostId = 'cursor' | 'vscode' | 'github' | 'claude-desktop';
+export interface HostConfigFile {
+    host: HostId;
+    path: string;
+    rootKey: 'mcpServers' | 'servers';
+    payload: Record<string, unknown>;
+}
+export declare function envFilePlaceholder(envPath: string): string;
+export declare function buildStdioEntry(envPath: string): StdioEntry;
+export declare function buildRemoteEntry(mcpPublicUrl: string): RemoteEntry;
+export declare function buildOAuthConnectEntry(mcpPublicUrl: string): RemoteEntry;
+/** Cursor / Claude Desktop — root key `mcpServers`, stdio shape. */
+export declare function buildMcpServersConfig(entry: StdioEntry | RemoteEntry): Record<string, unknown>;
+/** VS Code / GitHub Copilot — root key `servers`, requires `type`. */
+export declare function buildVsCodeServersConfig(entry: StdioEntry | RemoteEntry, transport?: 'stdio' | 'http'): Record<string, unknown>;
+export declare function cursorConfigPath(): string;
+export declare function vscodeUserMcpPath(): string;
+/** VS Code workspace config — share with team via source control. */
+export declare function vscodeWorkspaceMcpPath(projectRoot?: string): string;
+export declare function claudeDesktopConfigPath(): string;
+export declare function mergeCursorConfig(entry: StdioEntry | RemoteEntry, serverKey?: string): string;
+export declare function mergeVsCodeConfig(entry: StdioEntry | RemoteEntry, transport?: 'stdio' | 'http'): string;
+export declare function mergeVsCodeWorkspaceConfig(entry: StdioEntry | RemoteEntry, transport?: 'stdio' | 'http', projectRoot?: string): string;
+export declare function mergeClaudeDesktopConfig(entry: StdioEntry, serverKey?: string): string;
+export declare function resolveMcpPublicUrl(apiBase: string): string;
+export declare function claudeCodeAddCommand(mcpPublicUrl: string, mode?: 'oauth' | 'remote'): string;
+export interface SetupHostResult {
+    host: HostId;
+    path: string;
+    written: boolean;
+}
+export declare function mergeGitHubConfig(entry: StdioEntry | RemoteEntry, transport?: 'stdio' | 'http', projectRoot?: string): string;
+export declare function writeAllHostConfigs(envPath: string, mode: 'stdio' | 'remote' | 'oauth', mcpPublicUrl: string, projectRoot?: string): SetupHostResult[];

package/dist/lib/host-config.js

@@ -0,0 +1,200 @@
+/**
+ * Single source of truth for MCP server identity and per-host JSON configs.
+ * Hosts differ only by root key and field names — builders stay DRY here.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** npm scoped package under org gpsglobal-ai (see docs/57-mcp/018-npm-publish-and-cicd.md). */
+export const NPM_PACKAGE = '@gpsglobal-ai/gpsglobal';
+/** MCP protocol server key in mcp.json — short, stable across hosts. */
+export const MCP_SERVER_KEY = 'gpsglobal';
+/** CLI binary name after install (`npm i -g` → `gpsglobal` command). */
+export const CLI_BIN = 'gpsglobal';
+/** @alias NPM_PACKAGE */
+export const PACKAGE = NPM_PACKAGE;
+export function envFilePlaceholder(envPath) {
+    return envPath.replace(os.homedir(), '${userHome}');
+}
+export function buildStdioEntry(envPath) {
+    return {
+        command: 'npx',
+        args: ['-y', NPM_PACKAGE, '--stdio'],
+        envFile: envFilePlaceholder(envPath),
+    };
+}
+export function buildRemoteEntry(mcpPublicUrl) {
+    return {
+        url: `${mcpPublicUrl.replace(/\/+$/, '')}/mcp`,
+        headers: {
+            Authorization: 'Bearer ${env:GPS_ACCESS_TOKEN}',
+        },
+    };
+}
+export function buildOAuthConnectEntry(mcpPublicUrl) {
+    return {
+        url: `${mcpPublicUrl.replace(/\/+$/, '')}/mcp`,
+    };
+}
+/** Cursor / Claude Desktop — root key `mcpServers`, stdio shape. */
+export function buildMcpServersConfig(entry) {
+    return { mcpServers: { [MCP_SERVER_KEY]: entry } };
+}
+/** VS Code / GitHub Copilot — root key `servers`, requires `type`. */
+export function buildVsCodeServersConfig(entry, transport = 'stdio') {
+    if ('url' in entry) {
+        return {
+            servers: {
+                [MCP_SERVER_KEY]: {
+                    type: 'http',
+                    url: entry.url,
+                    ...(entry.headers ? { headers: entry.headers } : {}),
+                },
+            },
+        };
+    }
+    return {
+        servers: {
+            [MCP_SERVER_KEY]: {
+                type: 'stdio',
+                command: entry.command,
+                args: entry.args,
+                ...(entry.envFile ? { envFile: entry.envFile } : {}),
+                ...(entry.env ? { env: entry.env } : {}),
+            },
+        },
+    };
+}
+export function cursorConfigPath() {
+    return path.join(os.homedir(), '.cursor', 'mcp.json');
+}
+export function vscodeUserMcpPath() {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library/Application Support/Code/User/mcp.json');
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA ?? os.homedir(), 'Code', 'User', 'mcp.json');
+    }
+    return path.join(os.homedir(), '.config', 'Code', 'User', 'mcp.json');
+}
+/** VS Code workspace config — share with team via source control. */
+export function vscodeWorkspaceMcpPath(projectRoot = process.cwd()) {
+    return path.join(projectRoot, '.vscode', 'mcp.json');
+}
+export function claudeDesktopConfigPath() {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json');
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA ?? os.homedir(), 'Claude', 'claude_desktop_config.json');
+    }
+    return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+}
+function mergeJsonConfig(configPath, rootKey, serverKey, entry) {
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const merged = {
+        ...existing,
+        [rootKey]: {
+            ...(existing[rootKey] ?? {}),
+            [serverKey]: entry,
+        },
+    };
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+    return configPath;
+}
+export function mergeCursorConfig(entry, serverKey = MCP_SERVER_KEY) {
+    return mergeJsonConfig(cursorConfigPath(), 'mcpServers', serverKey, entry);
+}
+function mergeVsCodeConfigAt(configPath, entry, transport = 'stdio') {
+    const built = buildVsCodeServersConfig(entry, transport);
+    const servers = built.servers[MCP_SERVER_KEY];
+    return mergeJsonConfig(configPath, 'servers', MCP_SERVER_KEY, servers);
+}
+export function mergeVsCodeConfig(entry, transport = 'stdio') {
+    return mergeVsCodeConfigAt(vscodeUserMcpPath(), entry, transport);
+}
+export function mergeVsCodeWorkspaceConfig(entry, transport = 'stdio', projectRoot = process.cwd()) {
+    return mergeVsCodeConfigAt(vscodeWorkspaceMcpPath(projectRoot), entry, transport);
+}
+export function mergeClaudeDesktopConfig(entry, serverKey = MCP_SERVER_KEY) {
+    return mergeJsonConfig(claudeDesktopConfigPath(), 'mcpServers', serverKey, entry);
+}
+export function resolveMcpPublicUrl(apiBase) {
+    const normalized = apiBase.replace(/\/+$/, '');
+    if (normalized.includes('localhost') || normalized.includes('127.0.0.1')) {
+        return process.env.GPS_MCP_PUBLIC_URL ?? 'http://localhost:3100';
+    }
+    return process.env.GPS_MCP_PUBLIC_URL ?? 'https://lp.gpsglobal.ai';
+}
+export function claudeCodeAddCommand(mcpPublicUrl, mode = 'oauth') {
+    const url = `${mcpPublicUrl.replace(/\/+$/, '')}/mcp`;
+    if (mode === 'oauth') {
+        return `claude mcp add --scope user --transport http ${MCP_SERVER_KEY} ${url}`;
+    }
+    return `claude mcp add --scope user --transport http ${MCP_SERVER_KEY} ${url} --header "Authorization: Bearer $GPS_ACCESS_TOKEN"`;
+}
+export function mergeGitHubConfig(entry, transport = 'stdio', projectRoot = process.cwd()) {
+    const configPath = path.join(projectRoot, '.github', 'mcp.json');
+    const built = buildVsCodeServersConfig(entry, transport);
+    const servers = built.servers[MCP_SERVER_KEY];
+    return mergeJsonConfig(configPath, 'servers', MCP_SERVER_KEY, servers);
+}
+export function writeAllHostConfigs(envPath, mode, mcpPublicUrl, projectRoot = process.cwd()) {
+    const results = [];
+    const stdio = buildStdioEntry(envPath);
+    const remote = buildRemoteEntry(mcpPublicUrl);
+    const oauth = buildOAuthConnectEntry(mcpPublicUrl);
+    const cursorEntry = mode === 'oauth' ? oauth : mode === 'remote' ? remote : stdio;
+    results.push({ host: 'cursor', path: mergeCursorConfig(cursorEntry), written: true });
+    const vscodeEntry = mode === 'oauth' ? oauth : mode === 'remote' ? remote : stdio;
+    const vscodeTransport = mode === 'stdio' ? 'stdio' : 'http';
+    try {
+        results.push({
+            host: 'vscode',
+            path: mergeVsCodeConfig(vscodeEntry, vscodeTransport),
+            written: true,
+        });
+        results.push({
+            host: 'vscode',
+            path: mergeVsCodeWorkspaceConfig(vscodeEntry, vscodeTransport, projectRoot),
+            written: true,
+        });
+    }
+    catch {
+        results.push({ host: 'vscode', path: vscodeUserMcpPath(), written: false });
+    }
+    if (mode === 'stdio') {
+        try {
+            results.push({
+                host: 'claude-desktop',
+                path: mergeClaudeDesktopConfig(stdio),
+                written: true,
+            });
+        }
+        catch {
+            results.push({ host: 'claude-desktop', path: claudeDesktopConfigPath(), written: false });
+        }
+    }
+    if (mode === 'oauth' || mode === 'remote') {
+        try {
+            results.push({
+                host: 'github',
+                path: mergeGitHubConfig(vscodeEntry, vscodeTransport, projectRoot),
+                written: true,
+            });
+        }
+        catch {
+            results.push({ host: 'github', path: path.join(projectRoot, '.github', 'mcp.json'), written: false });
+        }
+    }
+    return results;
+}

package/dist/lib/jwt.d.ts

@@ -0,0 +1,9 @@
+/** Decode GPS JWT claims without verification — backend validates on API calls. */
+export interface GpsJwtClaims {
+    sub?: string;
+    lpId?: string;
+    role?: string;
+    aud?: string | string[];
+    scope?: string;
+}
+export declare function decodeGpsJwt(token: string): GpsJwtClaims;

package/dist/lib/jwt.js

@@ -0,0 +1,12 @@
+export function decodeGpsJwt(token) {
+    const parts = token.split('.');
+    if (parts.length < 2)
+        return {};
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/lib/pkce.d.ts

@@ -0,0 +1,6 @@
+export interface PkcePair {
+    codeVerifier: string;
+    codeChallenge: string;
+}
+export declare function generatePkce(): PkcePair;
+export declare function randomState(): string;

package/dist/lib/pkce.js

@@ -0,0 +1,11 @@
+import { createHash, randomBytes } from 'node:crypto';
+export function generatePkce() {
+    const codeVerifier = randomBytes(32).toString('base64url');
+    const codeChallenge = createHash('sha256')
+        .update(codeVerifier)
+        .digest('base64url');
+    return { codeVerifier, codeChallenge };
+}
+export function randomState() {
+    return randomBytes(16).toString('base64url');
+}

package/dist/lib/token-policy.d.ts

@@ -0,0 +1,14 @@
+import type { GpsJwtClaims } from './jwt.js';
+export declare const MCP_SCOPE = "mcp:read";
+export interface McpTokenPolicyOptions {
+    /** Expected resource URL, e.g. https://lp.gpsglobal.ai/mcp */
+    resourceUrl: string;
+    /** Reject tokens whose aud claim does not match resourceUrl */
+    strictAudience?: boolean;
+}
+/**
+ * Token passthrough audit (docs/57-mcp/004-auth-and-security.md):
+ * - MCP HTTP validates aud + scope + role before proxying to backend
+ * - Never forwards unvalidated tokens; backend re-validates JWT signature
+ */
+export declare function assertMcpHttpToken(claims: GpsJwtClaims, opts: McpTokenPolicyOptions): void;

package/dist/lib/token-policy.js

@@ -0,0 +1,27 @@
+export const MCP_SCOPE = 'mcp:read';
+/**
+ * Token passthrough audit (docs/57-mcp/004-auth-and-security.md):
+ * - MCP HTTP validates aud + scope + role before proxying to backend
+ * - Never forwards unvalidated tokens; backend re-validates JWT signature
+ */
+export function assertMcpHttpToken(claims, opts) {
+    if (!claims.lpId) {
+        throw new Error('Token missing lpId claim');
+    }
+    const aud = claims.aud;
+    const normalizedResource = opts.resourceUrl.replace(/\/+$/, '');
+    if (aud) {
+        const audValue = Array.isArray(aud) ? aud[0] : aud;
+        const normalizedAud = String(audValue).replace(/\/+$/, '');
+        if (normalizedAud !== normalizedResource) {
+            throw new Error(`Token audience mismatch (expected ${normalizedResource})`);
+        }
+    }
+    else if (opts.strictAudience) {
+        throw new Error('Token missing aud claim — use OAuth Connect or npx gpsglobal login --browser');
+    }
+    const scope = claims.scope;
+    if (scope && !String(scope).includes(MCP_SCOPE)) {
+        throw new Error(`Token missing required scope ${MCP_SCOPE}`);
+    }
+}

package/dist/server/factory.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GpsApiClient } from '../clients/gps-api.js';
+export declare function createGpsMcpServer(client: GpsApiClient): McpServer;

package/dist/server/factory.js

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerGpsTools } from '../tools/register.js';
+const SERVER_NAME = process.env.MCP_SERVER_NAME ?? 'gpsglobal';
+const SERVER_VERSION = process.env.MCP_SERVER_VERSION ?? '1.4.0';
+export function createGpsMcpServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    registerGpsTools(server, client);
+    return server;
+}

package/dist/tools/register.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { GpsApiClient } from '../clients/gps-api.js';
+export declare function registerGpsTools(server: McpServer, client: GpsApiClient): void;