@gpsglobal-ai/gpsglobal 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog — gpsglobal
+
+## 1.4.1 — 2026-06-17
+
+- **npm scope:** publish as `@gpsglobal-ai/gpsglobal` under org `gpsglobal-ai`
+- MCP server key remains **`gpsglobal`**; CLI bin **`gpsglobal`**
+- Trusted Publishing workflow: `.github/workflows/npm-publish-mcp.yml`
+- RFC 8707 `resource` parameter validation on OAuth authorize
+- AS metadata `scopes_supported: ["mcp:read"]`
+- `setup` writes VS Code **workspace** `.vscode/mcp.json` + fixes oauth mode
+- E2E **MCP-25** + docs [`017`](./017-multi-host-oauth-connect.md), [`018`](./018-npm-publish-and-cicd.md)
+
+## 1.4.0 — 2026-06-17
+
+- **A+ security:** MCP OAuth tokens with `aud` + `scope: mcp:read` + 1h TTL (`JwtTokenProvider.createMcpOAuthToken`)
+- **`token-policy.ts`** — HTTP transport validates audience and scope before backend proxy
+- **G-11 closed:** `LpOwnershipGuard` no longer bypasses for `gp` role
+- OAuth `POST /token` accepts `application/x-www-form-urlencoded` (Cursor/Claude clients)
+- `setup --mode=oauth --host=all` writes GitHub Copilot `.github/mcp.json`
+- E2E **MCP-22..24** — OAuth Connect chain, form token, GP API 403
+
+## 1.3.0 — 2026-06-17
+
+- **Renamed** npm package and MCP server identity to **`gpsglobal`** (was `@gpsglobal/mcp-server` / `gps-lp-wiki`)
+- **`host-config.ts`** — DRY builders for Cursor, VS Code Copilot, GitHub Copilot, Claude Desktop
+- **`setup`** default `--host=all` — writes Cursor + VS Code + Claude Desktop configs in one pass
+- New templates: `vscode-mcp.json`, `github-mcp.json`, `github-mcp-oauth.json`
+- E2E MCP-21 + SOTA assessment doc (`docs/57-mcp/016-sota-assessment.md`)
+
+## 1.2.0 — 2026-06-17
+
+- `doctor` command, `setup --mode=oauth`, OAuth redirect policy for Cursor/Claude
+- E2E MCP-12..20 + auto-generated `evaluation-report.md`
+
+## 1.1.0 — 2026-06-17
+
+- `setup` — one-command browser login + Cursor `mcp.json` merge
+- `login --browser` — PKCE loopback OAuth via backend `/api/v2/oauth/mcp-cli`
+- `--http` — Streamable HTTP transport on `/mcp` with PRM + 401 WWW-Authenticate
+- Docker image + `docker-compose` `gps-mcp` service on port 3100
+- ECS `gps-mcp` service + ALB `/mcp/*` routing (infra)
+
+## 1.0.0 — 2026-06-17
+
+- Initial release: `list_funds`, `get_fund_wiki` tools
+- CLI: `login`, `login --refresh`, `status`, `print-config`, `--stdio`
+- JWT auth via `POST /api/v2/auth/signin` → `~/.gps/mcp.env`

package/README.md

@@ -0,0 +1,33 @@
+# @gpsglobal-ai/gpsglobal
+
+GPS LP fund wiki **MCP server** — `list_funds` and `get_fund_wiki` for Cursor, Copilot, and Claude.
+
+| | |
+|--|--|
+| **npm** | `@gpsglobal-ai/gpsglobal` |
+| **MCP server key** | `gpsglobal` |
+| **CLI** | `gpsglobal` (after install) |
+
+## Quick start
+
+```bash
+npx @gpsglobal-ai/gpsglobal setup
+```
+
+Browser sign-in → `~/.gps/mcp.env` → merges configs for **Cursor**, **VS Code**, and **Claude Desktop**.
+
+| Variant | Command |
+|---------|---------|
+| OAuth Connect (URL-only) | `npx @gpsglobal-ai/gpsglobal setup --mode=oauth` |
+| Health check | `npx @gpsglobal-ai/gpsglobal doctor` |
+| Config snippets | `npx @gpsglobal-ai/gpsglobal print-config` |
+
+## Docs
+
+- Repo spec: [`docs/57-mcp/`](../docs/57-mcp/000-INDEX.md)
+- npm publish & CI/CD: [`docs/57-mcp/018-npm-publish-and-cicd.md`](../docs/57-mcp/018-npm-publish-and-cicd.md)
+- Host configuration: [`docs/57-mcp/017-multi-host-oauth-connect.md`](../docs/57-mcp/017-multi-host-oauth-connect.md)
+
+## License
+
+UNLICENSED — private GPS software.

package/dist/cli/browser-login.d.ts

@@ -0,0 +1,7 @@
+export interface BrowserLoginResult {
+    accessToken: string;
+    lpId: string;
+    username: string;
+    role: string;
+}
+export declare function browserLogin(apiBase: string): Promise<BrowserLoginResult>;

package/dist/cli/browser-login.js

@@ -0,0 +1,95 @@
+import http from 'node:http';
+import { createServer as createNetServer } from 'node:net';
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import axios from 'axios';
+import { generatePkce, randomState } from '../lib/pkce.js';
+import { normalizeApiBase, writeGpsEnvFile, DEFAULT_ENV_PATH } from '../config/env.js';
+const execAsync = promisify(exec);
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createNetServer();
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            if (!addr || typeof addr === 'string') {
+                reject(new Error('Could not bind loopback port'));
+                return;
+            }
+            const port = addr.port;
+            srv.close(() => resolve(port));
+        });
+        srv.on('error', reject);
+    });
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? `open "${url}"` :
+        process.platform === 'win32' ? `start "" "${url}"` :
+            `xdg-open "${url}"`;
+    exec(cmd, () => undefined);
+}
+export async function browserLogin(apiBase) {
+    const base = normalizeApiBase(apiBase);
+    const port = await findFreePort();
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const { codeVerifier, codeChallenge } = generatePkce();
+    const state = randomState();
+    const authorizeUrl = new URL(`${base}/api/v2/oauth/mcp-cli/authorize`);
+    authorizeUrl.searchParams.set('redirect_uri', redirectUri);
+    authorizeUrl.searchParams.set('state', state);
+    authorizeUrl.searchParams.set('code_challenge', codeChallenge);
+    authorizeUrl.searchParams.set('code_challenge_method', 'S256');
+    const codePromise = new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+            if (url.pathname !== '/callback') {
+                res.writeHead(404).end('Not found');
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const returnedState = url.searchParams.get('state');
+            if (!code || returnedState !== state) {
+                res.writeHead(400).end('Invalid callback');
+                reject(new Error('OAuth callback missing code or state mismatch'));
+                server.close();
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(`<!DOCTYPE html><html><body style="font-family:system-ui;background:#09090b;color:#fafafa;display:flex;align-items:center;justify-content:center;min-height:100vh">
+        <div style="text-align:center"><h1 style="color:#d4af37">GPS MCP connected</h1><p>You can close this tab and return to your terminal.</p></div></body></html>`);
+            resolve(code);
+            server.close();
+        });
+        server.listen(port, '127.0.0.1');
+        server.on('error', reject);
+    });
+    console.log(`Opening browser for GPS sign-in…\n${authorizeUrl.href}\n`);
+    openBrowser(authorizeUrl.href);
+    const code = await Promise.race([
+        codePromise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('Browser login timed out after 3 minutes')), 180_000)),
+    ]);
+    const tokenResp = await axios.post(`${base}/api/v2/oauth/mcp-cli/token`, {
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+    }, { validateStatus: () => true });
+    if (tokenResp.status >= 400) {
+        const desc = tokenResp.data?.error_description ?? tokenResp.statusText;
+        throw new Error(`Token exchange failed: ${desc}`);
+    }
+    const data = tokenResp.data;
+    writeGpsEnvFile({
+        apiBase: base,
+        accessToken: data.access_token,
+        lpId: data.lp_id,
+        role: data.role,
+        username: data.username,
+    }, DEFAULT_ENV_PATH);
+    return {
+        accessToken: data.access_token,
+        lpId: data.lp_id,
+        username: data.username,
+        role: data.role,
+    };
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,10 @@
+export interface DoctorResult {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail: string;
+    }>;
+}
+export declare function runDoctor(): Promise<DoctorResult>;
+export declare function printDoctor(result: DoctorResult): void;

package/dist/cli/doctor.js

@@ -0,0 +1,90 @@
+import axios from 'axios';
+import { GpsApiClient } from '../clients/gps-api.js';
+import { loadGpsConfig, normalizeApiBase, DEFAULT_ENV_PATH } from '../config/env.js';
+import { decodeGpsJwt } from '../lib/jwt.js';
+export async function runDoctor() {
+    const checks = [];
+    let config;
+    try {
+        config = loadGpsConfig();
+        checks.push({ name: 'credentials', ok: true, detail: `~/.gps/mcp.env · lp=${config.lpId}` });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        checks.push({ name: 'credentials', ok: false, detail: msg });
+        return { ok: false, checks };
+    }
+    const claims = decodeGpsJwt(config.accessToken);
+    if (!claims.lpId) {
+        checks.push({ name: 'jwt', ok: false, detail: 'Token missing lpId claim' });
+    }
+    else {
+        checks.push({ name: 'jwt', ok: true, detail: `role=${claims.role ?? config.role}` });
+    }
+    const apiBase = normalizeApiBase(config.apiBase);
+    try {
+        const health = await axios.get(`${apiBase}/api/health`, { timeout: 10_000, validateStatus: () => true });
+        checks.push({
+            name: 'backend',
+            ok: health.status === 200,
+            detail: `${apiBase}/api/health → ${health.status}`,
+        });
+    }
+    catch (err) {
+        checks.push({
+            name: 'backend',
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    try {
+        const client = new GpsApiClient(config);
+        const funds = await client.listFunds();
+        checks.push({
+            name: 'vault',
+            ok: funds.length >= 0,
+            detail: `${funds.length} fund(s) visible`,
+        });
+    }
+    catch (err) {
+        checks.push({
+            name: 'vault',
+            ok: false,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const mcpUrl = process.env.GPS_MCP_PUBLIC_URL ?? 'http://localhost:3100';
+    try {
+        const mcpHealth = await axios.get(`${mcpUrl}/health`, { timeout: 5_000, validateStatus: () => true });
+        if (mcpHealth.status === 404) {
+            checks.push({ name: 'mcp-http', ok: true, detail: 'not running (stdio mode OK)' });
+        }
+        else {
+            checks.push({
+                name: 'mcp-http',
+                ok: mcpHealth.status === 200,
+                detail: `${mcpUrl}/health → ${mcpHealth.status}`,
+            });
+        }
+    }
+    catch {
+        checks.push({ name: 'mcp-http', ok: true, detail: 'not running (stdio mode OK)' });
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+}
+export function printDoctor(result) {
+    console.log('GPS MCP doctor\n');
+    for (const c of result.checks) {
+        const icon = c.ok ? '✓' : '✗';
+        console.log(`  ${icon} ${c.name}: ${c.detail}`);
+    }
+    console.log();
+    if (!result.ok) {
+        console.log('Fix: npx gpsglobal setup');
+        console.log(`     or: npx gpsglobal login --refresh`);
+        console.log(`     env: ${DEFAULT_ENV_PATH}`);
+    }
+    else {
+        console.log('All checks passed. Restart Cursor if tools are not visible.');
+    }
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1,9 @@
+export type SetupMode = 'stdio' | 'remote' | 'oauth' | 'both';
+export type SetupHost = 'cursor' | 'vscode' | 'claude-desktop' | 'claude-code' | 'all';
+export interface SetupOptions {
+    apiBase?: string;
+    host?: SetupHost;
+    useBrowser?: boolean;
+    mode?: SetupMode;
+}
+export declare function runSetup(options: SetupOptions): Promise<void>;

package/dist/cli/setup.js

@@ -0,0 +1,52 @@
+import { browserLogin } from './browser-login.js';
+import { DEFAULT_ENV_PATH, normalizeApiBase } from '../config/env.js';
+import { MCP_SERVER_KEY, PACKAGE, claudeCodeAddCommand, mergeVsCodeConfig, mergeVsCodeWorkspaceConfig, mergeClaudeDesktopConfig, mergeCursorConfig, buildOAuthConnectEntry, buildRemoteEntry, buildStdioEntry, resolveMcpPublicUrl, writeAllHostConfigs, } from '../lib/host-config.js';
+export async function runSetup(options) {
+    const apiBase = normalizeApiBase(options.apiBase ?? process.env.GPS_API_BASE ?? 'http://localhost:8080');
+    const host = options.host ?? 'all';
+    const useBrowser = options.useBrowser ?? true;
+    const mode = options.mode ?? 'stdio';
+    const mcpPublic = resolveMcpPublicUrl(apiBase);
+    console.log(`GPS MCP setup — configure ${MCP_SERVER_KEY} for your AI tools\n`);
+    if (useBrowser) {
+        const result = await browserLogin(apiBase);
+        console.log(`\n✓ Signed in as ${result.username} (${result.lpId})`);
+        console.log(`✓ Credentials saved to ${DEFAULT_ENV_PATH}`);
+    }
+    else {
+        console.log('Using existing ~/.gps/mcp.env');
+    }
+    if (host === 'all') {
+        const results = writeAllHostConfigs(DEFAULT_ENV_PATH, mode === 'both' ? 'stdio' : mode, mcpPublic);
+        for (const r of results) {
+            const icon = r.written ? '✓' : '○';
+            console.log(`${icon} ${r.host}: ${r.path}`);
+        }
+        console.log(`\n  Claude Code (CLI): ${claudeCodeAddCommand(mcpPublic, mode === 'oauth' ? 'oauth' : 'remote')}`);
+        console.log('  Then run `/mcp` in Claude Code → Connect if prompted.');
+    }
+    else if (host === 'cursor') {
+        const entry = mode === 'oauth' ? buildOAuthConnectEntry(mcpPublic)
+            : mode === 'remote' ? buildRemoteEntry(mcpPublic)
+                : buildStdioEntry(DEFAULT_ENV_PATH);
+        console.log(`✓ Cursor → ${mergeCursorConfig(entry)}`);
+    }
+    else if (host === 'vscode') {
+        const entry = mode === 'oauth' ? buildOAuthConnectEntry(mcpPublic)
+            : mode === 'remote' ? buildRemoteEntry(mcpPublic)
+                : buildStdioEntry(DEFAULT_ENV_PATH);
+        const transport = mode === 'stdio' ? 'stdio' : 'http';
+        console.log(`✓ VS Code Copilot (user) → ${mergeVsCodeConfig(entry, transport)}`);
+        console.log(`✓ VS Code Copilot (workspace) → ${mergeVsCodeWorkspaceConfig(entry, transport)}`);
+        console.log('  Restart VS Code or run: MCP: List Servers');
+    }
+    else if (host === 'claude-desktop') {
+        console.log(`✓ Claude Desktop → ${mergeClaudeDesktopConfig(buildStdioEntry(DEFAULT_ENV_PATH))}`);
+        console.log('  Restart Claude Desktop.');
+    }
+    else if (host === 'claude-code') {
+        console.log(`\nRun:\n  ${claudeCodeAddCommand(mcpPublic, mode === 'oauth' ? 'oauth' : 'remote')}`);
+    }
+    console.log(`\nVerify: npx ${PACKAGE} doctor`);
+    console.log(`Done. Ask your AI: "list my GPS funds using ${MCP_SERVER_KEY}"`);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { GpsApiClient } from './clients/gps-api.js';
+import { DEFAULT_ENV_PATH, loadGpsConfig, normalizeApiBase, writeGpsEnvFile, } from './config/env.js';
+import { startStdioServer, startHttpFromEnv } from './index.js';
+import { browserLogin } from './cli/browser-login.js';
+import { runSetup } from './cli/setup.js';
+import { runDoctor, printDoctor } from './cli/doctor.js';
+import { MCP_SERVER_KEY, PACKAGE, buildMcpServersConfig, buildOAuthConnectEntry, buildRemoteEntry, buildStdioEntry, buildVsCodeServersConfig, resolveMcpPublicUrl, } from './lib/host-config.js';
+function printConfig(envPath) {
+    const apiBase = normalizeApiBase(process.env.GPS_API_BASE ?? 'http://localhost:8080');
+    const mcpPublic = resolveMcpPublicUrl(apiBase);
+    const stdio = buildStdioEntry(envPath);
+    const remote = buildRemoteEntry(mcpPublic);
+    const oauth = buildOAuthConnectEntry(mcpPublic);
+    console.log(`
+═══ Easiest: one command (all major hosts) ═══
+  npx ${PACKAGE} setup
+  npx ${PACKAGE} setup --mode=oauth   ← OAuth Connect (URL-only)
+
+═══ Cursor / Claude Desktop (mcpServers) ═══
+${JSON.stringify(buildMcpServersConfig(stdio), null, 2)}
+
+═══ VS Code / GitHub Copilot (servers) ═══
+${JSON.stringify(buildVsCodeServersConfig(stdio), null, 2)}
+
+═══ Remote HTTP ═══
+${JSON.stringify(buildMcpServersConfig(remote), null, 2)}
+
+═══ OAuth Connect (no token in JSON) ═══
+${JSON.stringify(buildMcpServersConfig(oauth), null, 2)}
+
+Server key: ${MCP_SERVER_KEY}
+Docs: docs/57-mcp/010-client-configuration.md
+API base: ${apiBase}
+`);
+}
+async function promptHidden(question) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runLogin(refresh, useBrowser) {
+    const apiBase = normalizeApiBase(process.env.GPS_API_BASE ?? 'http://localhost:8080');
+    if (useBrowser) {
+        const result = await browserLogin(apiBase);
+        console.log(`\n✓ Credentials saved to ${DEFAULT_ENV_PATH}`);
+        if (refresh)
+            console.log('Token refreshed.');
+        console.log(`  LP ID: ${result.lpId}`);
+        console.log(`  Role:  ${result.role}`);
+        printConfig(DEFAULT_ENV_PATH);
+        return;
+    }
+    const defaultUser = process.env.GPS_USERNAME ?? 'user';
+    const username = (await promptHidden(`GPS username [${defaultUser}]: `)).trim() || defaultUser;
+    const password = await promptHidden('GPS password: ');
+    if (!password)
+        throw new Error('Password is required');
+    const body = await GpsApiClient.signIn(apiBase, username, password);
+    writeGpsEnvFile({
+        apiBase,
+        accessToken: body.accessToken,
+        lpId: body.lpId,
+        role: body.role,
+        username: body.username,
+    });
+    console.log(`\n✓ Credentials saved to ${DEFAULT_ENV_PATH} (mode 600)`);
+    if (refresh)
+        console.log('Token refreshed.');
+    console.log(`  LP ID: ${body.lpId}`);
+    console.log(`  Role:  ${body.role}`);
+    printConfig(DEFAULT_ENV_PATH);
+}
+function runStatus() {
+    try {
+        const cfg = loadGpsConfig();
+        const masked = cfg.accessToken.length > 12
+            ? `${cfg.accessToken.slice(0, 6)}…${cfg.accessToken.slice(-4)}`
+            : '(set)';
+        console.log(`GPS_API_BASE=${cfg.apiBase}`);
+        console.log(`GPS_LP_ID=${cfg.lpId}`);
+        console.log(`GPS_ROLE=${cfg.role}`);
+        console.log(`GPS_ACCESS_TOKEN=${masked}`);
+        console.log(`Env file: ${process.env.GPS_MCP_ENV_PATH ?? DEFAULT_ENV_PATH}`);
+        console.log(`\nIf tools fail with 401, run: npx ${PACKAGE} login --refresh`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(msg);
+        process.exit(1);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--stdio')) {
+        await startStdioServer();
+        return;
+    }
+    if (args.includes('--http')) {
+        await startHttpFromEnv();
+        return;
+    }
+    const cmd = args[0];
+    if (!cmd || cmd === 'help' || args.includes('--help')) {
+        console.log(`Usage:
+  npx ${PACKAGE} setup              ← easiest: all hosts (Cursor, VS Code, Claude Desktop)
+  npx ${PACKAGE} setup --mode=oauth ← Cursor Connect (URL-only, no envFile)
+  npx ${PACKAGE} doctor             ← verify credentials + backend
+  npx ${PACKAGE} login [--browser] [--refresh]
+  npx ${PACKAGE} status
+  npx ${PACKAGE} print-config
+  npx ${PACKAGE} --stdio
+  npx ${PACKAGE} --http
+`);
+        return;
+    }
+    if (cmd === 'setup') {
+        const hostArg = args.find((a) => a.startsWith('--host='));
+        const modeArg = args.find((a) => a.startsWith('--mode='));
+        const host = hostArg?.split('=')[1];
+        const mode = modeArg?.split('=')[1];
+        await runSetup({
+            host: host ?? 'all',
+            useBrowser: !args.includes('--no-browser'),
+            mode: mode ?? 'stdio',
+        });
+        return;
+    }
+    if (cmd === 'doctor') {
+        const result = await runDoctor();
+        printDoctor(result);
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
+    if (cmd === 'login') {
+        await runLogin(args.includes('--refresh'), args.includes('--browser'));
+        return;
+    }
+    if (cmd === 'status') {
+        runStatus();
+        return;
+    }
+    if (cmd === 'print-config') {
+        printConfig(process.env.GPS_MCP_ENV_PATH ?? DEFAULT_ENV_PATH);
+        return;
+    }
+    console.error(`Unknown command: ${cmd}`);
+    process.exit(1);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(msg);
+    process.exit(1);
+});

package/dist/clients/gps-api.d.ts

@@ -0,0 +1,43 @@
+import { type GpsEnvConfig } from '../config/env.js';
+export interface ApiResponse<T> {
+    success: boolean;
+    body?: T;
+    message?: string;
+}
+export interface SignInBody {
+    accessToken: string;
+    lpId: string;
+    username: string;
+    role: string;
+}
+export interface FundListItem {
+    fundId: string;
+    metadata?: {
+        fund_name?: string;
+        fund_subtitle?: string;
+        closing_date?: string;
+    };
+    hasExtraction?: boolean;
+    hasWiki?: boolean;
+    strategy?: string;
+    geography?: string;
+    sector?: string;
+    fundSummary?: string;
+}
+export interface WikiContentBody {
+    lp_id: string;
+    fund_id: string;
+    fund_name: string;
+    has_wiki: boolean;
+    content: string;
+    wiki_status: string;
+}
+export declare class GpsApiClient {
+    private readonly http;
+    readonly config: GpsEnvConfig;
+    constructor(config: GpsEnvConfig);
+    static signIn(apiBase: string, username: string, password: string): Promise<SignInBody>;
+    private request;
+    listFunds(lpId?: string): Promise<FundListItem[]>;
+    getWikiContent(lpId: string, fundId: string): Promise<WikiContentBody>;
+}

package/dist/clients/gps-api.js

@@ -0,0 +1,61 @@
+import axios from 'axios';
+import { normalizeApiBase } from '../config/env.js';
+import { decodeGpsJwt } from '../lib/jwt.js';
+function unwrap(json) {
+    if (json && typeof json === 'object' && 'success' in json) {
+        if (!json.success) {
+            throw new Error(json.message ?? 'GPS API request failed');
+        }
+        if (json.body !== undefined)
+            return json.body;
+    }
+    return json;
+}
+export class GpsApiClient {
+    http;
+    config;
+    constructor(config) {
+        const claims = decodeGpsJwt(config.accessToken);
+        this.config = {
+            ...config,
+            lpId: config.lpId || claims.lpId || '',
+            role: config.role || claims.role || 'lp',
+            username: config.username || claims.sub || '',
+        };
+        this.http = axios.create({
+            baseURL: `${normalizeApiBase(config.apiBase)}/api/v2`,
+            headers: { Authorization: `Bearer ${config.accessToken}` },
+            timeout: 60_000,
+            validateStatus: () => true,
+        });
+    }
+    static async signIn(apiBase, username, password) {
+        const resp = await axios.post(`${normalizeApiBase(apiBase)}/api/v2/auth/signin`, { username, password }, { validateStatus: () => true });
+        if (resp.status === 401 || resp.status === 403) {
+            throw new Error('Sign-in failed: invalid username or password');
+        }
+        const json = resp.data;
+        const body = unwrap(json);
+        if (!body.accessToken || !body.lpId) {
+            throw new Error('Sign-in response missing accessToken or lpId');
+        }
+        return body;
+    }
+    async request(method, url) {
+        const resp = await this.http.request({ method, url });
+        if (resp.status === 401) {
+            throw new Error('Authentication expired or invalid. Run: npx @gpsglobal-ai/gpsglobal login --refresh');
+        }
+        if (resp.status === 403) {
+            throw new Error('Access denied. Your account may not have LP vault access.');
+        }
+        return unwrap(resp.data);
+    }
+    async listFunds(lpId) {
+        const id = lpId ?? this.config.lpId;
+        return this.request('get', `/triage/${encodeURIComponent(id)}`);
+    }
+    async getWikiContent(lpId, fundId) {
+        return this.request('get', `/triage/${encodeURIComponent(lpId)}/${encodeURIComponent(fundId)}/wiki-content`);
+    }
+}

package/dist/config/env.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_ENV_PATH: string;
+export interface GpsEnvConfig {
+    apiBase: string;
+    accessToken: string;
+    lpId: string;
+    role: string;
+    username: string;
+}
+export declare function parseEnvFile(content: string): Record<string, string>;
+export declare function loadGpsConfig(envPath?: string): GpsEnvConfig;
+export declare function normalizeApiBase(base: string): string;
+export declare function writeGpsEnvFile(config: Omit<GpsEnvConfig, 'role' | 'username'> & {
+    role: string;
+    username: string;
+}, envPath?: string): void;
+export declare function assertMcpEligibleRole(role: string): void;