@gpsglobal-ai/gpsglobal 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog — gpsglobal
 
+## 1.4.6 — 2026-06-21
+
+- **`get_fund_wiki` default `format=linked`** — `{P18}` → markdown link to LP Workspace `?tab=analyze#page=18`
+- **`format=raw`** — byte-identical NMG wiki.md (MCP-17 parity); **`format=summary`** unchanged
+- Edge cases: multi-page `{P3, P7}`, conflict `{P3≠P7}`, divider pages (no link), page clamp to `extracted_pages`
+- Docs: [`docs/57-mcp/020-wiki-linked-citations.md`](../docs/57-mcp/020-wiki-linked-citations.md)
+
+## 1.4.5 — 2026-06-21
+
+- **Production defaults:** `setup` and `login` use `https://lp.gpsglobal.ai` (not `localhost:8080`)
+- **`setup` default mode:** `oauth` — Cursor/VS Code/GitHub get URL-only `https://lp.gpsglobal.ai/mcp`
+- **Claude Desktop:** still gets stdio + `envFile` when mode is `oauth` (Desktop has no reliable HTTP OAuth)
+- **`doctor`:** probes `${apiBase}/mcp` → expects 401 on production (not localhost:3100)
+- Local dev: `GPS_API_BASE=http://localhost:8080 npx @gpsglobal-ai/gpsglobal setup --mode=stdio`
+
 ## 1.4.4 — 2026-06-18
 
 - CI: disable npm provenance (private GitHub repo — OIDC publish still works)

package/README.md

@@ -28,21 +28,27 @@ Data never leaves GPS infrastructure except through your authenticated session
 
 ## Quick start (recommended)
 
-One command — browser sign-in, credentials saved locally, configs merged for major AI hosts:
+One command — browser sign-in at **production**, credentials saved locally, configs merged for major AI hosts:
 
 ```bash
 npx @gpsglobal-ai/gpsglobal setup
 ```
 
-This writes `~/.gps/mcp.env` (mode `600`) and updates **Cursor**, **VS Code**, and **Claude Desktop** configs.
+This opens `https://lp.gpsglobal.ai` for OAuth, writes `~/.gps/mcp.env` (mode `600`), and updates **Cursor** (OAuth URL), **VS Code**, **GitHub Copilot**, and **Claude Desktop** (stdio) configs.
 
 **Restart your AI tool**, then ask: *"List my GPS funds using gpsglobal"*.
 
+**Local Docker dev** (backend on `localhost:8080`):
+
+```bash
+GPS_API_BASE=http://localhost:8080 npx @gpsglobal-ai/gpsglobal setup --mode=stdio
+```
+
 ### Other commands
 
 | Goal | Command |
 |------|---------|
-| OAuth Connect (URL-only, no token in config) | `npx @gpsglobal-ai/gpsglobal setup --mode=oauth` |
+| stdio-only (all hosts) | `npx @gpsglobal-ai/gpsglobal setup --mode=stdio` |
 | Verify install + backend reachability | `npx @gpsglobal-ai/gpsglobal doctor` |
 | Print config snippets for all hosts | `npx @gpsglobal-ai/gpsglobal print-config` |
 | Refresh credentials | `npx @gpsglobal-ai/gpsglobal login --browser --refresh` |
@@ -60,9 +66,9 @@ gpsglobal setup
 
 | Host | Setup mode | Config key |
 |------|------------|------------|
-| **Cursor** | `setup` or `setup --mode=oauth` | `gpsglobal` |
+| **Cursor** | `setup` (default oauth) | `gpsglobal` |
 | **VS Code / GitHub Copilot** | `setup` | `gpsglobal` |
-| **Claude Desktop** | `setup` (stdio) | `gpsglobal` |
+| **Claude Desktop** | `setup` (stdio via envFile) | `gpsglobal` |
 | **Claude Code** | `claude mcp add --transport http gpsglobal https://lp.gpsglobal.ai/mcp` | `gpsglobal` |
 
 **OAuth Connect (production):** hosts discover auth via `https://lp.gpsglobal.ai/mcp` — no manual JWT paste.
@@ -129,7 +135,7 @@ gpsglobal setup
 |-------|-----|
 | Tools return 401 | `npx @gpsglobal-ai/gpsglobal login --browser --refresh` |
 | Host shows disconnected | Restart the AI app after `setup` |
-| `doctor` fails | Ensure backend is running; check `GPS_API_BASE` in `~/.gps/mcp.env` |
+| `doctor` fails | Ensure you are whitelisted on prod; check `GPS_API_BASE` in `~/.gps/mcp.env` (should be `https://lp.gpsglobal.ai`) |
 | OAuth Connect loop | Confirm Cursor/VS Code config is URL-only (no stale Bearer header) |
 
 ---

package/dist/cli/doctor.js

@@ -2,6 +2,7 @@ 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';
+import { resolveMcpPublicUrl } from '../lib/host-config.js';
 export async function runDoctor() {
     const checks = [];
     let config;
@@ -53,22 +54,29 @@ export async function runDoctor() {
             detail: err instanceof Error ? err.message : String(err),
         });
     }
-    const mcpUrl = process.env.GPS_MCP_PUBLIC_URL ?? 'http://localhost:3100';
+    const mcpUrl = resolveMcpPublicUrl(config.apiBase);
     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)' });
+        const mcpProbe = await axios.get(`${mcpUrl}/mcp`, {
+            timeout: 10_000,
+            validateStatus: () => true,
+            maxRedirects: 0,
+        });
+        if (mcpProbe.status === 401) {
+            checks.push({ name: 'mcp-http', ok: true, detail: `${mcpUrl}/mcp → 401 (discovery OK)` });
+        }
+        else if (mcpProbe.status === 404) {
+            checks.push({ name: 'mcp-http', ok: true, detail: 'stdio mode (no remote /mcp)' });
         }
         else {
             checks.push({
                 name: 'mcp-http',
-                ok: mcpHealth.status === 200,
-                detail: `${mcpUrl}/health → ${mcpHealth.status}`,
+                ok: mcpProbe.status === 200,
+                detail: `${mcpUrl}/mcp → ${mcpProbe.status}`,
             });
         }
     }
     catch {
-        checks.push({ name: 'mcp-http', ok: true, detail: 'not running (stdio mode OK)' });
+        checks.push({ name: 'mcp-http', ok: true, detail: 'remote MCP unreachable (stdio mode OK)' });
     }
     return { ok: checks.every((c) => c.ok), checks };
 }

package/dist/cli/setup.js

@@ -1,13 +1,14 @@
 import { browserLogin } from './browser-login.js';
-import { DEFAULT_ENV_PATH, normalizeApiBase } from '../config/env.js';
+import { DEFAULT_ENV_PATH, LOCAL_GPS_API_BASE, normalizeApiBase, resolveDefaultApiBase } 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 apiBase = normalizeApiBase(options.apiBase ?? resolveDefaultApiBase());
     const host = options.host ?? 'all';
     const useBrowser = options.useBrowser ?? true;
-    const mode = options.mode ?? 'stdio';
+    const mode = options.mode ?? 'oauth';
     const mcpPublic = resolveMcpPublicUrl(apiBase);
-    console.log(`GPS MCP setup — configure ${MCP_SERVER_KEY} for your AI tools\n`);
+    console.log(`GPS MCP setup — configure ${MCP_SERVER_KEY} for your AI tools`);
+    console.log(`  API: ${apiBase}  ·  MCP: ${mcpPublic}/mcp  ·  mode: ${mode}\n`);
     if (useBrowser) {
         const result = await browserLogin(apiBase);
         console.log(`\n✓ Signed in as ${result.username} (${result.lpId})`);
@@ -48,5 +49,6 @@ export async function runSetup(options) {
         console.log(`\nRun:\n  ${claudeCodeAddCommand(mcpPublic, mode === 'oauth' ? 'oauth' : 'remote')}`);
     }
     console.log(`\nVerify: npx ${PACKAGE} doctor`);
+    console.log(`Local dev: GPS_API_BASE=${LOCAL_GPS_API_BASE} npx ${PACKAGE} setup --mode=stdio`);
     console.log(`Done. Ask your AI: "list my GPS funds using ${MCP_SERVER_KEY}"`);
 }

package/dist/cli.js

@@ -2,14 +2,14 @@
 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 { DEFAULT_ENV_PATH, loadGpsConfig, resolveDefaultApiBase, 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 apiBase = resolveDefaultApiBase();
     const mcpPublic = resolveMcpPublicUrl(apiBase);
     const stdio = buildStdioEntry(envPath);
     const remote = buildRemoteEntry(mcpPublic);
@@ -17,7 +17,7 @@ function printConfig(envPath) {
     console.log(`
 ═══ Easiest: one command (all major hosts) ═══
   npx ${PACKAGE} setup
-  npx ${PACKAGE} setup --mode=oauth   ← OAuth Connect (URL-only)
+  npx ${PACKAGE} setup --mode=stdio   ← local dev / Claude Desktop stdio-only
 
 ═══ Cursor / Claude Desktop (mcpServers) ═══
 ${JSON.stringify(buildMcpServersConfig(stdio), null, 2)}
@@ -46,7 +46,7 @@ async function promptHidden(question) {
     }
 }
 async function runLogin(refresh, useBrowser) {
-    const apiBase = normalizeApiBase(process.env.GPS_API_BASE ?? 'http://localhost:8080');
+    const apiBase = resolveDefaultApiBase();
     if (useBrowser) {
         const result = await browserLogin(apiBase);
         console.log(`\n✓ Credentials saved to ${DEFAULT_ENV_PATH}`);
@@ -109,8 +109,8 @@ async function main() {
     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} setup              ← production OAuth Connect (https://lp.gpsglobal.ai/mcp)
+  npx ${PACKAGE} setup --mode=stdio ← local dev (GPS_API_BASE=http://localhost:8080)
   npx ${PACKAGE} doctor             ← verify credentials + backend
   npx ${PACKAGE} login [--browser] [--refresh]
   npx ${PACKAGE} status
@@ -128,7 +128,7 @@ async function main() {
         await runSetup({
             host: host ?? 'all',
             useBrowser: !args.includes('--no-browser'),
-            mode: mode ?? 'stdio',
+            mode: mode ?? 'oauth',
         });
         return;
     }

package/dist/config/env.d.ts

@@ -1,4 +1,10 @@
 export declare const DEFAULT_ENV_PATH: string;
+/** Production LP Workspace origin — default for published npm package. */
+export declare const DEFAULT_GPS_API_BASE = "https://lp.gpsglobal.ai";
+/** Local Docker backend — opt-in via GPS_API_BASE for developers only. */
+export declare const LOCAL_GPS_API_BASE = "http://localhost:8080";
+/** Resolve API base: explicit env → production (not localhost). */
+export declare function resolveDefaultApiBase(): string;
 export interface GpsEnvConfig {
     apiBase: string;
     accessToken: string;

package/dist/config/env.js

@@ -2,6 +2,14 @@ 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');
+/** Production LP Workspace origin — default for published npm package. */
+export const DEFAULT_GPS_API_BASE = 'https://lp.gpsglobal.ai';
+/** Local Docker backend — opt-in via GPS_API_BASE for developers only. */
+export const LOCAL_GPS_API_BASE = 'http://localhost:8080';
+/** Resolve API base: explicit env → production (not localhost). */
+export function resolveDefaultApiBase() {
+    return normalizeApiBase(process.env.GPS_API_BASE ?? DEFAULT_GPS_API_BASE);
+}
 export function parseEnvFile(content) {
     const out = {};
     for (const line of content.split('\n')) {
@@ -36,7 +44,7 @@ export function loadGpsConfig(envPath = process.env.GPS_MCP_ENV_PATH ?? DEFAULT_
     }
     const parsed = parseEnvFile(fs.readFileSync(envPath, 'utf8'));
     const merged = {
-        apiBase: normalizeApiBase(parsed.GPS_API_BASE ?? 'http://localhost:8080'),
+        apiBase: normalizeApiBase(parsed.GPS_API_BASE ?? DEFAULT_GPS_API_BASE),
         accessToken: parsed.GPS_ACCESS_TOKEN ?? '',
         lpId: parsed.GPS_LP_ID ?? '',
         role: parsed.GPS_ROLE ?? 'lp',

package/dist/http.d.ts

@@ -3,6 +3,9 @@ export interface HttpServerOptions {
     host: string;
     apiBase: string;
     publicBaseUrl: string;
+    /** Public GPS API origin for OAuth AS in PRM (defaults to publicBaseUrl). */
+    publicApiBase?: string;
     enabled: boolean;
+    version?: string;
 }
 export declare function startHttpServer(opts: HttpServerOptions): Promise<void>;

package/dist/http.js

@@ -5,6 +5,7 @@ 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';
+import { oauthAuthorizationServerUrl, resolvePublicApiBase } from './lib/public-api-base.js';
 function parseBearer(req) {
     const h = req.headers.authorization;
     if (!h?.startsWith('Bearer '))
@@ -28,15 +29,21 @@ function sendUnauthorized(res, resourceMetadataUrl, 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`;
+    const publicApiBase = resolvePublicApiBase(opts.publicApiBase, opts.publicBaseUrl);
+    const authServer = oauthAuthorizationServerUrl(publicApiBase);
+    const serviceVersion = opts.version ?? process.env.GPS_MCP_VERSION ?? '1.4.4';
     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' });
+        res.json({ status: 'ok', service: 'gpsglobal', version: serviceVersion });
     });
     app.get('/.well-known/oauth-protected-resource', (_req, res) => {
+        if (!opts.enabled) {
+            res.status(503).json({ error: 'GPS MCP is temporarily disabled' });
+            return;
+        }
         res.json({
             resource: `${opts.publicBaseUrl}/mcp`,
             authorization_servers: [authServer],

package/dist/index.js

@@ -1,6 +1,6 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { GpsApiClient } from './clients/gps-api.js';
-import { loadGpsConfig, normalizeApiBase } from './config/env.js';
+import { loadGpsConfig, normalizeApiBase, LOCAL_GPS_API_BASE } from './config/env.js';
 import { createGpsMcpServer } from './server/factory.js';
 import { startHttpServer } from './http.js';
 export async function startStdioServer() {
@@ -13,8 +13,17 @@ export async function startStdioServer() {
 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 apiBase = normalizeApiBase(process.env.GPS_API_BASE ?? LOCAL_GPS_API_BASE);
     const publicBaseUrl = normalizeApiBase(process.env.GPS_MCP_PUBLIC_URL ?? `http://localhost:${port}`);
+    const publicApiBase = normalizeApiBase(process.env.GPS_MCP_PUBLIC_API_BASE ?? publicBaseUrl);
     const enabled = process.env.GPS_MCP_ENABLED !== 'false';
-    await startHttpServer({ port, host, apiBase, publicBaseUrl, enabled });
+    await startHttpServer({
+        port,
+        host,
+        apiBase,
+        publicBaseUrl,
+        publicApiBase,
+        enabled,
+        version: process.env.GPS_MCP_VERSION,
+    });
 }

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

@@ -40,7 +40,7 @@ export declare function mergeCursorConfig(entry: StdioEntry | RemoteEntry, serve
 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 { resolveMcpPublicUrl } from './public-url.js';
 export declare function claudeCodeAddCommand(mcpPublicUrl: string, mode?: 'oauth' | 'remote'): string;
 export interface SetupHostResult {
     host: HostId;

package/dist/lib/host-config.js

@@ -128,13 +128,7 @@ export function mergeVsCodeWorkspaceConfig(entry, transport = 'stdio', projectRo
 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 { resolveMcpPublicUrl } from './public-url.js';
 export function claudeCodeAddCommand(mcpPublicUrl, mode = 'oauth') {
     const url = `${mcpPublicUrl.replace(/\/+$/, '')}/mcp`;
     if (mode === 'oauth') {
@@ -172,7 +166,8 @@ export function writeAllHostConfigs(envPath, mode, mcpPublicUrl, projectRoot = p
     catch {
         results.push({ host: 'vscode', path: vscodeUserMcpPath(), written: false });
     }
-    if (mode === 'stdio') {
+    // Claude Desktop has no reliable remote HTTP + OAuth — always stdio + envFile.
+    if (mode === 'stdio' || mode === 'oauth') {
         try {
             results.push({
                 host: 'claude-desktop',

package/dist/lib/nmg-lineage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * NMG lineage token helpers — mirrors ml-service/services/nmg.py LINEAGE_RE.
+ * Spec: docs/05-incidents/01-citation-navigation-red-team/06-references/08-wiki-format.md
+ */
+/** Match `{P3}`, `{P3, P7}`, `{P3≠P7}` (whitespace tolerant). */
+export declare const LINEAGE_RE: RegExp;
+export interface ParsedLineage {
+    raw: string;
+    pages: number[];
+    conflicting: boolean;
+}
+export declare function parseLineageToken(token: string): ParsedLineage | null;
+export declare function findLineageTokens(text: string): ParsedLineage[];
+export declare function clampPage(page: number, maxPage?: number): number;

package/dist/lib/nmg-lineage.js

@@ -0,0 +1,34 @@
+/**
+ * NMG lineage token helpers — mirrors ml-service/services/nmg.py LINEAGE_RE.
+ * Spec: docs/05-incidents/01-citation-navigation-red-team/06-references/08-wiki-format.md
+ */
+/** Match `{P3}`, `{P3, P7}`, `{P3≠P7}` (whitespace tolerant). */
+export const LINEAGE_RE = /\{\s*P(\d+)((?:\s*[,≠]\s*P\d+)*)\s*\}/g;
+const PAGE_NUM_RE = /P(\d+)/g;
+export function parseLineageToken(token) {
+    const m = token.match(/^\{\s*P(\d+)((?:\s*[,≠]\s*P\d+)*)\s*\}$/);
+    if (!m)
+        return null;
+    const inner = m[0];
+    const conflicting = inner.includes('≠');
+    const pages = [...inner.matchAll(PAGE_NUM_RE)]
+        .map((x) => Number(x[1]))
+        .filter((n) => Number.isFinite(n) && n > 0);
+    return { raw: inner, pages, conflicting };
+}
+export function findLineageTokens(text) {
+    const out = [];
+    for (const m of text.matchAll(LINEAGE_RE)) {
+        const parsed = parseLineageToken(m[0]);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+export function clampPage(page, maxPage) {
+    if (!Number.isFinite(page) || page < 1)
+        return 1;
+    if (maxPage != null && maxPage > 0)
+        return Math.min(page, maxPage);
+    return page;
+}

package/dist/lib/public-api-base.d.ts

@@ -0,0 +1,3 @@
+/** Public GPS API origin for OAuth PRM (external clients). Internal GPS_API_BASE may differ in ECS. */
+export declare function resolvePublicApiBase(publicApiBase: string | undefined, publicMcpUrl: string): string;
+export declare function oauthAuthorizationServerUrl(publicApiBase: string): string;

package/dist/lib/public-api-base.js

@@ -0,0 +1,8 @@
+/** Public GPS API origin for OAuth PRM (external clients). Internal GPS_API_BASE may differ in ECS. */
+export function resolvePublicApiBase(publicApiBase, publicMcpUrl) {
+    const base = (publicApiBase ?? publicMcpUrl).replace(/\/+$/, '');
+    return base;
+}
+export function oauthAuthorizationServerUrl(publicApiBase) {
+    return `${publicApiBase.replace(/\/+$/, '')}/api/v2/oauth/mcp-cli`;
+}

package/dist/lib/public-url.d.ts

@@ -0,0 +1,14 @@
+/** LP Workspace deep-link path (FundDetailPage + Event Browser artifacts). */
+export declare const FUND_ANALYZE_DEEP_LINK_PATTERN = "/lp/{lpId}/fund/{fundId}?tab=analyze#page={N}";
+export interface WikiLinkedContext {
+    lpId: string;
+    fundId: string;
+    /** Public LP Workspace origin, e.g. https://lp.gpsglobal.ai or http://localhost:5173 */
+    workspacePublicUrl: string;
+}
+export declare function isLocalHostOrigin(url: string): boolean;
+/** Public MCP Streamable HTTP origin (e.g. https://lp.gpsglobal.ai or http://localhost:3100). */
+export declare function resolveMcpPublicUrl(apiBase: string): string;
+/** Public LP Workspace PWA origin for fund PDF page links (e.g. https://lp.gpsglobal.ai or :5173). */
+export declare function resolveWorkspacePublicUrl(apiBase: string): string;
+export declare function buildFundAnalyzePageUrl(workspacePublicUrl: string, lpId: string, fundId: string, page: number): string;

package/dist/lib/public-url.js

@@ -0,0 +1,30 @@
+/**
+ * Public origin resolution for MCP clients — single place for prod vs local URLs.
+ * MCP HTTP (/mcp), LP Workspace PWA (/lp/…), and API base may differ in local Docker.
+ */
+import { DEFAULT_GPS_API_BASE, normalizeApiBase } from '../config/env.js';
+/** LP Workspace deep-link path (FundDetailPage + Event Browser artifacts). */
+export const FUND_ANALYZE_DEEP_LINK_PATTERN = '/lp/{lpId}/fund/{fundId}?tab=analyze#page={N}';
+export function isLocalHostOrigin(url) {
+    const normalized = normalizeApiBase(url);
+    return normalized.includes('localhost') || normalized.includes('127.0.0.1');
+}
+/** Public MCP Streamable HTTP origin (e.g. https://lp.gpsglobal.ai or http://localhost:3100). */
+export function resolveMcpPublicUrl(apiBase) {
+    if (isLocalHostOrigin(apiBase)) {
+        return process.env.GPS_MCP_PUBLIC_URL ?? 'http://localhost:3100';
+    }
+    const normalized = normalizeApiBase(apiBase);
+    return process.env.GPS_MCP_PUBLIC_URL ?? (normalized || DEFAULT_GPS_API_BASE);
+}
+/** Public LP Workspace PWA origin for fund PDF page links (e.g. https://lp.gpsglobal.ai or :5173). */
+export function resolveWorkspacePublicUrl(apiBase) {
+    if (isLocalHostOrigin(apiBase)) {
+        return process.env.GPS_WORKSPACE_PUBLIC_URL ?? 'http://localhost:5173';
+    }
+    return process.env.GPS_MCP_PUBLIC_URL ?? DEFAULT_GPS_API_BASE;
+}
+export function buildFundAnalyzePageUrl(workspacePublicUrl, lpId, fundId, page) {
+    const base = normalizeApiBase(workspacePublicUrl);
+    return `${base}/lp/${encodeURIComponent(lpId)}/fund/${encodeURIComponent(fundId)}?tab=analyze#page=${page}`;
+}

package/dist/lib/wiki-linked.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Transform NMG wiki `{Pn}` lineage tokens into LP Workspace deep links.
+ *
+ * Deep-link convention: see public-url.ts / docs/57-mcp/020-wiki-linked-citations.md
+ * Canonical wiki.md on disk stays unchanged — transform at MCP read time only.
+ */
+import { type WikiLinkedContext } from './public-url.js';
+export type { WikiLinkedContext } from './public-url.js';
+export type WikiServeFormat = 'linked' | 'raw' | 'summary';
+export interface WikiLinkedMeta {
+    format: 'linked';
+    divider_pages: number[];
+    extracted_pages?: number;
+    lineage_tokens_transformed: number;
+    links_emitted: number;
+}
+export interface SplitWiki {
+    frontMatterBlock: string;
+    body: string;
+    dividerPages: number[];
+    extractedPages?: number;
+}
+/** Split YAML front matter; parse divider_pages + extracted_pages for edge-case handling. */
+export declare function splitWikiFrontMatter(raw: string): SplitWiki;
+/** Transform `{Pn}` tokens in wiki body to markdown page links. Front matter is preserved verbatim. */
+export declare function transformWikiBodyWithPageLinks(body: string, ctx: WikiLinkedContext, opts?: {
+    dividerPages?: number[];
+    extractedPages?: number;
+}): {
+    text: string;
+    tokensTransformed: number;
+    linksEmitted: number;
+};
+export declare function transformWikiWithPageLinks(rawWiki: string, ctx: WikiLinkedContext): {
+    content: string;
+    meta: WikiLinkedMeta;
+};

package/dist/lib/wiki-linked.js

@@ -0,0 +1,96 @@
+/**
+ * Transform NMG wiki `{Pn}` lineage tokens into LP Workspace deep links.
+ *
+ * Deep-link convention: see public-url.ts / docs/57-mcp/020-wiki-linked-citations.md
+ * Canonical wiki.md on disk stays unchanged — transform at MCP read time only.
+ */
+import { buildFundAnalyzePageUrl, } from './public-url.js';
+import { clampPage, LINEAGE_RE, parseLineageToken } from './nmg-lineage.js';
+/** Split YAML front matter; parse divider_pages + extracted_pages for edge-case handling. */
+export function splitWikiFrontMatter(raw) {
+    const fm = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!fm) {
+        return { frontMatterBlock: '', body: raw, dividerPages: [], extractedPages: undefined };
+    }
+    const yaml = fm[1];
+    const dividerPages = parseYamlIntList(yaml, 'divider_pages');
+    const extractedPages = parseYamlInt(yaml, 'extracted_pages');
+    return {
+        frontMatterBlock: fm[0],
+        body: raw.slice(fm[0].length),
+        dividerPages,
+        extractedPages,
+    };
+}
+function parseYamlIntList(yaml, key) {
+    const m = yaml.match(new RegExp(`^${key}:\\s*\\[([^\\]]*)\\]`, 'm'));
+    if (!m)
+        return [];
+    return m[1]
+        .split(',')
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n) && n > 0);
+}
+function parseYamlInt(yaml, key) {
+    const m = yaml.match(new RegExp(`^${key}:\\s*(\\d+)`, 'm'));
+    if (!m)
+        return undefined;
+    const n = parseInt(m[1], 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+function renderPageLink(page, ctx, opts) {
+    if (opts.dividerPages.includes(page)) {
+        return `[Page ${page} (divider — no document content)](#gps-divider-page-${page})`;
+    }
+    const clamped = clampPage(page, opts.maxPage);
+    const label = clamped !== page ? `Page ${page}→${clamped}` : `Page ${clamped}`;
+    return `[${label}](${buildFundAnalyzePageUrl(ctx.workspacePublicUrl, ctx.lpId, ctx.fundId, clamped)})`;
+}
+function renderLineageLinks(parsed, ctx, opts) {
+    if (parsed.pages.length === 0)
+        return parsed.raw;
+    if (parsed.conflicting) {
+        return parsed.pages.map((p) => renderPageLink(p, ctx, opts)).join(' **vs** ');
+    }
+    if (parsed.pages.length === 1) {
+        return renderPageLink(parsed.pages[0], ctx, opts);
+    }
+    return parsed.pages.map((p) => renderPageLink(p, ctx, opts)).join(', ');
+}
+/** Transform `{Pn}` tokens in wiki body to markdown page links. Front matter is preserved verbatim. */
+export function transformWikiBodyWithPageLinks(body, ctx, opts = {}) {
+    const linkOpts = {
+        dividerPages: opts.dividerPages ?? [],
+        maxPage: opts.extractedPages,
+    };
+    let tokensTransformed = 0;
+    let linksEmitted = 0;
+    const text = body.replace(LINEAGE_RE, (match) => {
+        const parsed = parseLineageToken(match);
+        if (!parsed)
+            return match;
+        tokensTransformed += 1;
+        linksEmitted += parsed.pages.filter((p) => !linkOpts.dividerPages.includes(p)).length;
+        return renderLineageLinks(parsed, ctx, linkOpts);
+    });
+    return { text, tokensTransformed, linksEmitted };
+}
+export function transformWikiWithPageLinks(rawWiki, ctx) {
+    const split = splitWikiFrontMatter(rawWiki);
+    const { text, tokensTransformed, linksEmitted } = transformWikiBodyWithPageLinks(split.body, ctx, { dividerPages: split.dividerPages, extractedPages: split.extractedPages });
+    const preamble = [
+        '> **GPS linked wiki** — citation links open **Analyze → PDF** at the cited page in LP Workspace.',
+        '> Requires GPS sign-in. Canonical NMG tokens `{Pn}` on disk; request `format=raw` for byte-identical wiki.md.',
+        '',
+    ].join('\n');
+    return {
+        content: split.frontMatterBlock + preamble + text,
+        meta: {
+            format: 'linked',
+            divider_pages: split.dividerPages,
+            extracted_pages: split.extractedPages,
+            lineage_tokens_transformed: tokensTransformed,
+            links_emitted: linksEmitted,
+        },
+    };
+}

package/dist/lib/wiki-serve.d.ts

@@ -0,0 +1,17 @@
+import { type WikiLinkedMeta, type WikiServeFormat } from './wiki-linked.js';
+export interface ServeFundWikiInput {
+    content: string;
+    fundId: string;
+    lpId: string;
+    fundName: string;
+    wikiStatus: string;
+    format?: WikiServeFormat;
+}
+export interface ServeFundWikiResult {
+    body: string;
+    format: WikiServeFormat;
+    linkedMeta?: WikiLinkedMeta;
+}
+/** Transform or pass through wiki markdown per format. */
+export declare function serveFundWiki(input: ServeFundWikiInput): ServeFundWikiResult;
+export declare function buildFundWikiStructuredContent(input: ServeFundWikiInput, served: ServeFundWikiResult): Record<string, unknown>;

package/dist/lib/wiki-serve.js

@@ -0,0 +1,47 @@
+/**
+ * Serve fund wiki content in the requested format — SRP between tool registration and transform.
+ */
+import { resolveDefaultApiBase } from '../config/env.js';
+import { FUND_ANALYZE_DEEP_LINK_PATTERN, resolveWorkspacePublicUrl } from './public-url.js';
+import { splitWikiFrontMatter, transformWikiWithPageLinks, } from './wiki-linked.js';
+function wikiSummary(content) {
+    const { frontMatterBlock, body } = splitWikiFrontMatter(content);
+    const titles = body.split('\n').filter((l) => l.startsWith('#')).slice(0, 20);
+    if (!frontMatterBlock)
+        return titles.join('\n').trim();
+    return `${frontMatterBlock}${titles.join('\n')}`.trim();
+}
+function extractSchemaVersion(content) {
+    const m = content.match(/schema_version:\s*["']?([^"'\n]+)/);
+    return m?.[1]?.trim();
+}
+/** Transform or pass through wiki markdown per format. */
+export function serveFundWiki(input) {
+    const format = input.format ?? 'linked';
+    if (format === 'summary') {
+        return { body: wikiSummary(input.content), format };
+    }
+    if (format === 'raw') {
+        return { body: input.content, format };
+    }
+    const transformed = transformWikiWithPageLinks(input.content, {
+        lpId: input.lpId,
+        fundId: input.fundId,
+        workspacePublicUrl: resolveWorkspacePublicUrl(resolveDefaultApiBase()),
+    });
+    return { body: transformed.content, format, linkedMeta: transformed.meta };
+}
+export function buildFundWikiStructuredContent(input, served) {
+    return {
+        fund_id: input.fundId,
+        fund_name: input.fundName,
+        has_wiki: true,
+        wiki_status: input.wikiStatus,
+        format: served.format,
+        schema_version: extractSchemaVersion(input.content),
+        byte_length_raw: input.content.length,
+        byte_length: served.body.length,
+        pdf_deep_link_pattern: FUND_ANALYZE_DEEP_LINK_PATTERN,
+        ...(served.linkedMeta ?? {}),
+    };
+}

package/dist/tools/register.js

@@ -1,11 +1,16 @@
 import { z } from 'zod';
 import { assertMcpEligibleRole } from '../config/env.js';
+import { buildFundWikiStructuredContent, serveFundWiki } from '../lib/wiki-serve.js';
 const listFundsSchema = {
     include_closed: z.boolean().optional().describe('If false (default), omit funds whose closing_date is in the past.'),
 };
 const getFundWikiSchema = {
     fund_id: z.string().describe('Fund identifier from list_funds (e.g. fund_1776212451730_0).'),
-    format: z.enum(['markdown', 'summary']).optional().describe('markdown = full wiki; summary = YAML header + section titles only.'),
+    format: z
+        .enum(['linked', 'raw', 'summary'])
+        .optional()
+        .describe('linked (default) = {Pn} → clickable LP Workspace PDF page links; '
+        + 'raw = byte-identical NMG wiki.md from vault; summary = YAML header + section titles only.'),
 };
 function isClosed(closingDate) {
     if (!closingDate)
@@ -32,28 +37,6 @@ function mapFund(f) {
         fund_summary: f.fundSummary ?? '',
     };
 }
-function wikiSummary(content) {
-    const lines = content.split('\n');
-    const header = [];
-    let inYaml = false;
-    for (const line of lines) {
-        if (line.trim() === '---') {
-            inYaml = !inYaml;
-            header.push(line);
-            if (!inYaml && header.length > 1)
-                break;
-            continue;
-        }
-        if (inYaml)
-            header.push(line);
-    }
-    const titles = lines.filter((l) => l.startsWith('#')).slice(0, 20);
-    return [...header, '', ...titles].join('\n').trim();
-}
-function extractSchemaVersion(content) {
-    const m = content.match(/schema_version:\s*["']?([^"'\n]+)/);
-    return m?.[1]?.trim();
-}
 export function registerGpsTools(server, client) {
     server.registerTool('list_funds', {
         description: 'List all funds in the authenticated LP vault with metadata and has_wiki flags.',
@@ -74,7 +57,10 @@ export function registerGpsTools(server, client) {
         };
     });
     server.registerTool('get_fund_wiki', {
-        description: 'Retrieve NMG wiki markdown for one fund in the authenticated LP vault.',
+        description: 'Retrieve NMG fund wiki for the authenticated LP vault. '
+            + 'Default format=linked transforms {P18} lineage tokens into LP Workspace deep links '
+            + '(?tab=analyze#page=N) so hosts can cite "Page 18" with a clickable PDF anchor. '
+            + 'Use format=raw for canonical on-disk wiki.md (byte parity with API).',
         inputSchema: getFundWikiSchema,
     }, async ({ fund_id, format }) => {
         assertMcpEligibleRole(client.config.role);
@@ -92,17 +78,18 @@ export function registerGpsTools(server, client) {
                 isError: true,
             };
         }
-        const body = format === 'summary' ? wikiSummary(wiki.content) : wiki.content;
+        const serveInput = {
+            content: wiki.content,
+            fundId: fund_id,
+            lpId: client.config.lpId,
+            fundName: wiki.fund_name,
+            wikiStatus: wiki.wiki_status,
+            format,
+        };
+        const served = serveFundWiki(serveInput);
         return {
-            content: [{ type: 'text', text: body }],
-            structuredContent: {
-                fund_id: wiki.fund_id,
-                fund_name: wiki.fund_name,
-                has_wiki: true,
-                wiki_status: wiki.wiki_status,
-                schema_version: extractSchemaVersion(wiki.content),
-                byte_length: wiki.content.length,
-            },
+            content: [{ type: 'text', text: served.body }],
+            structuredContent: buildFundWikiStructuredContent(serveInput, served),
         };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gpsglobal-ai/gpsglobal",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "GPS LP fund wiki MCP server — list_funds and get_fund_wiki for Cursor, Copilot, Claude",
   "type": "module",
   "main": "./dist/index.js",