@gpsglobal-ai/gpsglobal 1.4.5 → 1.4.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — gpsglobal
 
+## 1.4.7 — 2026-06-21
+
+- **README** — document `get_fund_wiki` `format=linked` default (PDF page deep links)
+- **Docs sync** — `docs/57-mcp/` index, client config, production proof updated to v1.4.6+
+
+## 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`)

package/README.md

@@ -13,7 +13,7 @@ This package implements a [Model Context Protocol (MCP)](https://modelcontextpro
 | Tool | Description |
 |------|-------------|
 | `list_funds` | List funds in your LP vault (with `has_wiki` metadata) |
-| `get_fund_wiki` | Return the full markdown wiki for a fund |
+| `get_fund_wiki` | Return fund wiki markdown. **Default `format=linked`** turns `{P18}` citations into clickable PDF page links (`?tab=analyze#page=18`). Use `format=raw` for byte-identical on-disk wiki.md. |
 
 Data never leaves GPS infrastructure except through your authenticated session — the MCP proxies to `https://lp.gpsglobal.ai` with LP-scoped JWT or OAuth tokens.
 

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

@@ -5,7 +5,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { DEFAULT_GPS_API_BASE } from '../config/env.js';
 /** 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. */
@@ -129,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 ?? (normalized || DEFAULT_GPS_API_BASE);
-}
+export { resolveMcpPublicUrl } from './public-url.js';
 export function claudeCodeAddCommand(mcpPublicUrl, mode = 'oauth') {
     const url = `${mcpPublicUrl.replace(/\/+$/, '')}/mcp`;
     if (mode === 'oauth') {

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-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.5",
+  "version": "1.4.7",
   "description": "GPS LP fund wiki MCP server — list_funds and get_fund_wiki for Cursor, Copilot, Claude",
   "type": "module",
   "main": "./dist/index.js",