@phi-longevity/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @phi-longevity/mcp-server
+
+A Model Context Protocol (MCP) server that lets AI agents call **Phi Longevity's PRISM** longevity
+recommendation engine on **synthetic** biomarker panels.
+
+> 🛡️ **Synthetic / de-identified data only.** Do not submit protected health information (PHI). The
+> server is stateless and stores nothing. It is a credibility / agent-discoverability surface — not a
+> PHI-bearing or clinical-care surface.
+
+## Tools
+| Tool | What it does |
+|---|---|
+| `analyze_biomarkers` | Analyze a synthetic panel → 3-tier, evidence-cited recommendations (THIS WEEK / CONSIDER / ASK YOUR CLINICIAN). |
+| `list_supported_biomarkers` | The scored biomarkers + units + reference ranges, by clinical pillar. |
+| `get_methodology` | How the Phi Score works (5 pillars + weights) + link to the full methodology. |
+
+## Install / run
+```bash
+npm install
+npm run build
+PHI_MCP_KEY="phimcp_d29179fdd8b99b70a49ae26f434843cf" node dist/index.js
+```
+
+### Claude Desktop config (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "phi-longevity": {
+      "command": "npx",
+      "args": ["-y", "@phi-longevity/mcp-server"],
+      "env": {
+        "PHI_MCP_KEY": "phimcp_d29179fdd8b99b70a49ae26f434843cf"
+      }
+    }
+  }
+}
+```
+
+## Environment
+| Var | Required | Notes |
+|---|---|---|
+| `PHI_MCP_KEY` | yes | Your `@phi-longevity` access key (sent as `x-phi-mcp-key`). Published + revocable + rate-limited. |
+| `PHI_ENGINE_URL` | no | Override the default Phi MCP gateway URL (rarely needed). |
+
+## Status — v0 scaffold (2026-06-10)
+Built by cloud-cos. **Needs `npm install && npm run build` to validate against the live SDK** (the SDK
+wasn't installed in the scaffold environment). Decisions locked: revocable key + rate-limit · npm stdio ·
+no affiliate URLs by default · pkg `@phi-longevity/mcp-server` · own repo `phi-mcp-server`.
+
+### TODO before publish
+- `npm install && npm run build` → fix any SDK API drift (the `server.tool(...)` shape).
+- Sync `src/catalog.ts` with the canonical `BIOMARKER_CATALOG` (45 markers).
+- Gateway (`phi-mcp-gateway`) holds the engine secret server-side + validates `x-phi-mcp-key` + rate-limits. ✅
+- Local test with the synthetic peri fixtures (`dossier/v2.0/scenarios/`).
+- `agents.philongevity.com` landing page (separate; install snippet + 3 tools + no-PHI terms).
+- `npm publish --access public` under the `@phi-longevity` org.
+
+## HIPAA / privacy
+Synthetic-only at the protocol boundary; stateless; aggregate-only telemetry (counts/timing to stderr,
+never values or recommendation text); zero access to Firestore / the HIPAA datastore / user accounts.
+GDPR: v0 processes no personal data (synthetic only) → minimal exposure.

package/dist/catalog.js

@@ -0,0 +1,35 @@
+export const BIOMARKER_CATALOG = [
+    // Metabolic
+    { name: "Hemoglobin A1c", unit: "%", pillar: "Metabolic", refLow: 4.0, refHigh: 5.6 },
+    { name: "Fasting Glucose", unit: "mg/dL", pillar: "Metabolic", refLow: 70, refHigh: 99 },
+    { name: "Fasting Insulin", unit: "uIU/mL", pillar: "Metabolic", refLow: 2.6, refHigh: 24.9 },
+    { name: "Triglycerides", unit: "mg/dL", pillar: "Metabolic", refLow: 0, refHigh: 150 },
+    // Cardiovascular
+    { name: "ApoB", unit: "mg/dL", pillar: "Cardiovascular", refLow: 0, refHigh: 90 },
+    { name: "Lp(a)", unit: "nmol/L", pillar: "Cardiovascular", refLow: 0, refHigh: 75 },
+    { name: "LDL Cholesterol", unit: "mg/dL", pillar: "Cardiovascular", refLow: 0, refHigh: 100 },
+    { name: "HDL Cholesterol", unit: "mg/dL", pillar: "Cardiovascular", refLow: 40, refHigh: 60 },
+    { name: "Total Cholesterol", unit: "mg/dL", pillar: "Cardiovascular", refLow: 125, refHigh: 200 },
+    // Hormonal
+    { name: "TSH", unit: "uIU/mL", pillar: "Hormonal", refLow: 0.4, refHigh: 4.5 },
+    { name: "Free T4", unit: "ng/dL", pillar: "Hormonal", refLow: 0.8, refHigh: 1.8 },
+    { name: "Free T3", unit: "pg/mL", pillar: "Hormonal", refLow: 2.3, refHigh: 4.2 },
+    { name: "Testosterone", unit: "ng/dL", pillar: "Hormonal" },
+    { name: "Estradiol", unit: "pg/mL", pillar: "Hormonal" },
+    { name: "DHEA-S", unit: "ug/dL", pillar: "Hormonal" },
+    { name: "Cortisol", unit: "ug/dL", pillar: "Hormonal", refLow: 5, refHigh: 23 },
+    // Inflammation & Immunity
+    { name: "hs-CRP", unit: "mg/L", pillar: "Inflammation & Immunity", refLow: 0, refHigh: 3.0 },
+    { name: "Homocysteine", unit: "umol/L", pillar: "Inflammation & Immunity", refLow: 0, refHigh: 15 },
+    { name: "ESR", unit: "mm/hr", pillar: "Inflammation & Immunity", refLow: 0, refHigh: 20 },
+    { name: "Omega-3 Index", unit: "%", pillar: "Inflammation & Immunity", refLow: 8, refHigh: 12 },
+    // Foundational Health
+    { name: "eGFR", unit: "mL/min", pillar: "Foundational Health", refLow: 60, refHigh: 120 },
+    { name: "Creatinine", unit: "mg/dL", pillar: "Foundational Health", refLow: 0.6, refHigh: 1.3 },
+    { name: "ALT", unit: "U/L", pillar: "Foundational Health", refLow: 0, refHigh: 44 },
+    { name: "AST", unit: "U/L", pillar: "Foundational Health", refLow: 0, refHigh: 40 },
+    { name: "Vitamin D 25-OH", unit: "ng/mL", pillar: "Foundational Health", refLow: 30, refHigh: 100 },
+    { name: "Vitamin B12", unit: "pg/mL", pillar: "Foundational Health", refLow: 200, refHigh: 900 },
+    { name: "Ferritin", unit: "ng/mL", pillar: "Foundational Health", refLow: 30, refHigh: 400 },
+    { name: "Hemoglobin", unit: "g/dL", pillar: "Foundational Health", refLow: 13.5, refHigh: 17.5 },
+];

package/dist/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * @philongevity/mcp-server — Phi Longevity PRISM engine over MCP.
+ *
+ * Lets AI agents call Phi's longevity recommendation engine on SYNTHETIC biomarker panels
+ * and get back the structured 3-tier output (THIS WEEK / CONSIDER / ASK YOUR CLINICIAN) with
+ * evidence tiers + citations. A credibility / agent-discoverability surface — NOT a PHI surface.
+ *
+ * 🛡️ HIPAA posture (designed-in):
+ *  - SYNTHETIC / de-identified data only at the protocol boundary (stated in every tool description).
+ *  - STATELESS: proxies to the engine and returns; writes nothing, persists nothing.
+ *  - Aggregate-only telemetry to stderr: counts/timing, NEVER biomarker values or recommendation text.
+ *  - The x-migration-secret is injected server-side and NEVER exposed to the agent.
+ *  - Zero access to Firestore / the HIPAA datastore / user accounts. One upstream URL only.
+ *
+ * Env:
+ *   PHI_ENGINE_URL        (required) — runRecommendationsForBiomarkers Cloud Function URL
+ *   PHI_MIGRATION_SECRET  (required) — x-migration-secret header value (server-side only)
+ *   PHI_MCP_KEY           (optional) — published-but-revocable access key (sent to the engine for
+ *                                      rate-limit/validation; enforcement lives server-side)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { BIOMARKER_CATALOG } from "./catalog.js";
+const GATEWAY_URL = process.env.PHI_ENGINE_URL ?? "https://phi-mcp-gateway-bblwxa6cvq-uc.a.run.app";
+const MCP_KEY = process.env.PHI_MCP_KEY ?? "";
+const SYNTHETIC_WARNING = "For research/education with SYNTHETIC or de-identified data only. Do NOT submit protected health " +
+    "information (PHI). This endpoint is stateless and does not store inputs.";
+// ── Local courtesy rate-limit (defense in depth; real enforcement is server-side) ─────────────
+const RATE = { capacity: 20, refillPerSec: 0.5, tokens: 20, last: Date.now() };
+function allow() {
+    const now = Date.now();
+    RATE.tokens = Math.min(RATE.capacity, RATE.tokens + ((now - RATE.last) / 1000) * RATE.refillPerSec);
+    RATE.last = now;
+    if (RATE.tokens < 1)
+        return false;
+    RATE.tokens -= 1;
+    return true;
+}
+// ── Aggregate-only telemetry (stderr; NEVER values) ───────────────────────────────────────────
+function telemetry(ev) {
+    try {
+        process.stderr.write(JSON.stringify({ t: new Date().toISOString(), ...ev }) + "\n");
+    }
+    catch { /* noop */ }
+}
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+async function callEngine(body) {
+    if (!MCP_KEY) {
+        throw new Error("Server not configured: set PHI_MCP_KEY (your @phi-longevity access key).");
+    }
+    const headers = {
+        "Content-Type": "application/json",
+        "x-phi-mcp-key": MCP_KEY,
+    };
+    const res = await fetch(GATEWAY_URL, { method: "POST", headers, body: JSON.stringify(body) });
+    if (!res.ok)
+        throw new Error(`Gateway returned ${res.status}.`);
+    return res.json();
+}
+const server = new McpServer({ name: "phi-longevity", version: "0.1.0" }, {
+    instructions: "Phi Longevity PRISM — longevity-optimized analysis of biomarker panels. " + SYNTHETIC_WARNING,
+});
+// ── Tool 1: analyze_biomarkers (the core) ─────────────────────────────────────────────────────
+server.tool("analyze_biomarkers", "Analyze a SYNTHETIC biomarker panel with Phi Longevity's PRISM engine. Returns 3-tier, " +
+    "evidence-cited recommendations (THIS WEEK / CONSIDER / ASK YOUR CLINICIAN). " + SYNTHETIC_WARNING, {
+    biomarkers: z
+        .record(z.string(), z.number())
+        .describe("Map of biomarker name -> numeric value, e.g. { \"Hemoglobin A1c\": 5.4 }. SYNTHETIC ONLY."),
+    conditionFocus: z
+        .enum(["general_wellness", "type2_diabetes", "lupus", "cancer_survivorship"])
+        .optional()
+        .describe("Optional condition track. Default general_wellness."),
+    age: z.number().int().min(0).max(120).optional(),
+    biologicalSex: z.enum(["male", "female"]).optional(),
+    include_partner_options: z
+        .boolean()
+        .optional()
+        .describe("If true, include partner/product options. Default false (clean clinical output)."),
+}, async (args) => {
+    const t0 = Date.now();
+    if (!allow())
+        return textResult("Rate limit reached. Please retry in a moment.");
+    try {
+        // The engine expects biomarkers as an array of {name, value}; the tool takes an
+        // agent-friendly {name: value} map → transform here.
+        const biomarkerArray = Object.entries(args.biomarkers || {}).map(([name, value]) => ({ name, value }));
+        const out = await callEngine({
+            biomarkers: biomarkerArray,
+            conditionFocus: args.conditionFocus ?? "general_wellness",
+            age: args.age,
+            biologicalSex: args.biologicalSex,
+        });
+        const recs = args.include_partner_options
+            ? out.recommendations_v2_with_partners ?? out.recommendations_v2
+            : out.recommendations_v2;
+        telemetry({
+            tool: "analyze_biomarkers",
+            n_biomarkers: Object.keys(args.biomarkers || {}).length,
+            conditionFocus: args.conditionFocus ?? "general_wellness",
+            issues_count: Array.isArray(out.issues) ? out.issues.length : 0,
+            elapsed_ms: Date.now() - t0,
+        });
+        return textResult(JSON.stringify({ recommendations: recs, meta: out.meta, issues: out.issues }, null, 2));
+    }
+    catch (e) {
+        telemetry({ tool: "analyze_biomarkers", error: e.message, elapsed_ms: Date.now() - t0 });
+        return textResult(`Could not analyze: ${e.message}`);
+    }
+});
+// ── Tool 2: list_supported_biomarkers ─────────────────────────────────────────────────────────
+server.tool("list_supported_biomarkers", "List the biomarkers PRISM scores, with units and reference ranges, grouped by clinical pillar. " +
+    "Reference data only — no patient data.", {}, async () => {
+    telemetry({ tool: "list_supported_biomarkers", count: BIOMARKER_CATALOG.length });
+    return textResult(JSON.stringify({ biomarkers: BIOMARKER_CATALOG }, null, 2));
+});
+// ── Tool 3: get_methodology ───────────────────────────────────────────────────────────────────
+server.tool("get_methodology", "Summarize how the Phi Score works (5 clinical pillars + weights) and link to the full methodology.", {}, async () => {
+    telemetry({ tool: "get_methodology" });
+    return textResult(JSON.stringify({
+        phi_score: "0–100 weighted composite across five clinical pillars: Metabolic (30%), Cardiovascular (25%), " +
+            "Hormonal (20%), Inflammation & Immunity (15%), Foundational Health (10%). Compared against " +
+            "longevity-optimized reference ranges, not just standard lab normals.",
+        methodology_url: "https://philongevity.com/methodology",
+        note: "Decision support, not a diagnosis. Recommendations are evidence-tiered with citations. " + SYNTHETIC_WARNING,
+        source: "Phi Longevity (philongevity.com)",
+    }, null, 2));
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    telemetry({ event: "phi-mcp-server started", tools: 3 });
+}
+main().catch((e) => {
+    telemetry({ event: "fatal", error: e.message });
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@phi-longevity/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Phi Longevity — agents can call the PRISM longevity recommendation engine on SYNTHETIC biomarker panels. Synthetic/de-identified data only; no PHI; stateless.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "phi-mcp-server": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "keywords": ["mcp", "model-context-protocol", "longevity", "health", "biomarkers", "phi-longevity"]
+}