@theronap/cortex-mcp 0.4.2 → 0.4.4

package/bin/cortex-mcp.mjs

@@ -16,7 +16,7 @@
  * Get your token from the Cortex console → Connect your AI.
  */
 
-const VERSION = '0.4.2'
+const VERSION = '0.4.3'
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
@@ -51,7 +51,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
 // commands don't fall through into the server.
 if (cmd === 'setup') {
   const { runSetup } = await import('../lib/setup.mjs')
-  await runSetup(rest)
+  await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
 } else if (cmd === 'doctor') {

package/lib/capture.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from 'fs'
-import { fetchCortex, classify } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 
 // Claude Code Stop hook → POSTs a session digest to Cortex cloud, which
 // summarizes server-side and upserts ONE record per session. Node-native
@@ -32,7 +32,7 @@ function transcriptTail(path) {
 export async function runCapture() {
   const token = process.env.CORTEX_TOKEN
   if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
-  const base = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+  const base = resolveBase(process.env.CORTEX_URL)
 
   let hook = {}
   try { hook = JSON.parse(readStdin()) } catch { /* no/invalid stdin */ }
@@ -65,7 +65,7 @@ export async function runCapture() {
     const j = await res.json().catch(() => ({}))
     process.stderr.write(`cortex: ${j.inserted ? 'captured' : 'updated'} "${j.title ?? repo}" → ${repo}\n`)
   } else {
-    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'), res.headers.get('x-deny-reason'))
     process.stderr.write(`cortex: ingest failed — ${d.message}\n`)
   }
 }

package/lib/diagnose.mjs

@@ -6,19 +6,46 @@
 // to tell the truth about WHAT failed.
 //
 // KEY SIGNAL: the Cortex app ALWAYS returns JSON ({ error: ... }). So a NON-JSON body on a
-// 4xx/5xx means infrastructure handled the request, not Cortex auth — re-running setup or
-// regenerating the token will not help; it is usually transient and worth a retry.
+// 4xx/5xx means something else handled the request, not Cortex auth — re-running setup or
+// regenerating the token will not help. Two cases: (1) an egress allowlist block
+// (x-deny-reason: host_not_allowed) — NOT retriable, the host must be added to the allowlist;
+// (2) a transient infrastructure hiccup — retriable.
 
 export const isUuid = (s) =>
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s ?? '')
 
+// The production alias — exempt from Vercel Deployment Protection.
+export const CANONICAL_BASE = 'https://cortex-console.vercel.app'
+
+// Resolve the API base from CORTEX_URL. A Vercel *deployment* URL
+// (cortex-console-<hash>-<team>.vercel.app, or any non-canonical *.vercel.app) is guarded by
+// Deployment Protection and returns an HTML auth page to programmatic clients — which looks
+// exactly like an "infra block" (403/401, non-JSON). The production alias is exempt. So if
+// CORTEX_URL points at a deployment URL, we fall back to the alias (and warn on stderr). A real
+// custom domain (not *.vercel.app) is respected as-is. This makes the client robust to a stale
+// CORTEX_URL pointing at a protected preview/deployment — the root cause of the Windows 403.
+export function resolveBase(rawUrl) {
+  const raw = (rawUrl ?? '').trim()
+  if (!raw) return CANONICAL_BASE
+  let host
+  try { host = new URL(raw).host } catch { return CANONICAL_BASE }
+  if (host.endsWith('.vercel.app') && host !== 'cortex-console.vercel.app') {
+    process.stderr.write(
+      `cortex: CORTEX_URL (${raw}) is a protected Vercel deployment URL; using ${CANONICAL_BASE} instead.\n`,
+    )
+    return CANONICAL_BASE
+  }
+  return raw.replace(/\/$/, '')
+}
+
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 
 // A non-OK response → an actionable diagnosis: { kind, retriable, message }.
-//   kind: 'auth'  → token bad/revoked/wrong-deployment (NOT retriable)
-//         'infra' → blocked by infrastructure, non-JSON body (retriable, usually transient)
-//         'app'   → a real Cortex API error with a JSON message (retriable only if 5xx)
-export function classify(status, contentType, bodyText, requestId) {
+//   kind: 'auth'   → token bad/revoked/wrong-deployment (NOT retriable)
+//         'egress' → blocked by network egress allowlist (NOT retriable, not a Cortex/Vercel issue)
+//         'infra'  → blocked by infrastructure, non-JSON body (retriable, usually transient)
+//         'app'    → a real Cortex API error with a JSON message (retriable only if 5xx)
+export function classify(status, contentType, bodyText, requestId, denyReason) {
   const isJson = (contentType ?? '').includes('application/json')
   let appError = null
   if (isJson) { try { appError = JSON.parse(bodyText)?.error ?? null } catch { /* not json after all */ } }
@@ -32,6 +59,15 @@ export function classify(status, contentType, bodyText, requestId) {
         `the Cortex console → Connect your AI, then re-run setup.${rid}`,
     }
   }
+  if (denyReason === 'host_not_allowed' || /host (not in allowlist|not allowed)/i.test(bodyText ?? '')) {
+    return {
+      kind: 'egress', retriable: false,
+      message: `Blocked by your network's egress allowlist (HTTP ${status}: ${denyReason ?? 'host_not_allowed'}). ` +
+        `The request never left this environment — this is NOT a Cortex, token, or Vercel issue. ` +
+        `Add ${CANONICAL_BASE} to your environment's outbound allowlist, or run from a machine with open egress. ` +
+        `Re-running setup or regenerating the token will not help.${rid}`,
+    }
+  }
   if (!isJson) {
     return {
       kind: 'infra', retriable: true,
@@ -55,10 +91,11 @@ export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 4
     try {
       const res = await fetch(url, opts)
       const ct = res.headers.get('content-type') ?? ''
+      const denyReason = res.headers.get('x-deny-reason') ?? ''
       const transient =
         res.status === 429 ||
         res.status >= 500 ||
-        (res.status === 403 && !ct.includes('application/json')) // infra block, not app authz
+        (res.status === 403 && !ct.includes('application/json') && !denyReason) // egress block is not transient
       if (transient && attempt < retries) {
         await sleep(baseDelayMs * 2 ** attempt)
         continue
@@ -98,7 +135,7 @@ export async function checkToken(token, base) {
   const contentType = res.headers.get('content-type')
   const body = await res.text()
   if (!res.ok) {
-    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
+    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId, res.headers.get('x-deny-reason')) }
   }
   let projectCount
   try {

package/lib/doctor.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
-import { checkToken } from './diagnose.mjs'
+import { checkToken, resolveBase } from './diagnose.mjs'
 
 // `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
 //
@@ -25,7 +25,7 @@ function resolveToken() {
 }
 
 export async function runDoctor() {
-  const base = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+  const base = resolveBase(process.env.CORTEX_URL)
   const out = (m) => process.stdout.write(m + '\n')
 
   out('')

package/lib/server.mjs

@@ -1,14 +1,14 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import { fetchCortex, classify } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 
 // The Cortex MCP server (stdio). Serves the signed-in employee's scoped org
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
 export async function runServer(version) {
   const TOKEN = process.env.CORTEX_TOKEN
-  const BASE = (process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')
+  const BASE = resolveBase(process.env.CORTEX_URL)
 
   if (!TOKEN) {
     process.stderr.write('cortex-mcp: CORTEX_TOKEN is required. Get yours from the Cortex console → Connect your AI.\n')
@@ -25,7 +25,7 @@ export async function runServer(version) {
     const res = await fetchCortex(`${BASE}/api/mcp-context`, { headers: { Authorization: `Bearer ${TOKEN}` } })
     if (!res.ok) {
       const body = await res.text()
-      throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
+      throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id'), res.headers.get('x-deny-reason')).message)
     }
     const { context } = await res.json()
     cache = { text: context, ts: now }
@@ -92,7 +92,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not assemble story: ${e.message}` }] }
       }
       if (!res.ok) {
-        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'), res.headers.get('x-deny-reason'))
         return { content: [{ type: 'text', text: `Could not assemble story: ${d.message}` }] }
       }
       const { answer, sourceCount, sources } = await res.json()
@@ -124,7 +124,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not set privacy: ${e.message}` }] }
       }
       if (!res.ok) {
-        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'), res.headers.get('x-deny-reason'))
         return { content: [{ type: 'text', text: `Could not set privacy: ${d.message}` }] }
       }
       const out = await res.json()

package/lib/setup.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
-import { checkToken } from './diagnose.mjs'
+import { checkToken, resolveBase } from './diagnose.mjs'
 
 // One-command employee onboarding. Wires both:
 //   1. ~/.claude.json        → the cortex MCP server (context-serving)
@@ -32,7 +32,7 @@ function ensureDir(path) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
 }
 
-export async function runSetup(argv) {
+export async function runSetup(argv, version) {
   const token = argv[0]
   if (!token || token.startsWith('-')) {
     process.stderr.write(
@@ -41,7 +41,10 @@ export async function runSetup(argv) {
     )
     process.exit(1)
   }
-  const base = process.env.CORTEX_URL ?? 'https://cortex-console.vercel.app'
+  // Pin the wired commands to the installed version so the config can't later run a stale
+  // cached build (npx may reuse a cached older version for an unpinned spec).
+  const spec = version ? `${PKG}@${version}` : PKG
+  const base = resolveBase(process.env.CORTEX_URL)
   const home = homedir()
   const claudeJson = join(home, '.claude.json')
   const settingsJson = join(home, '.claude', 'settings.json')
@@ -62,7 +65,7 @@ export async function runSetup(argv) {
     cfg.mcpServers.cortex = {
       type: 'stdio',
       command: 'npx',
-      args: ['-y', PKG],
+      args: ['-y', spec],
       env: { CORTEX_TOKEN: token },
     }
     ensureDir(claudeJson)
@@ -84,7 +87,7 @@ export async function runSetup(argv) {
     s.hooks = s.hooks ?? {}
     s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
 
-    const captureCmd = `CORTEX_TOKEN=${token} npx -y ${PKG} capture`
+    const captureCmd = `CORTEX_TOKEN=${token} npx -y ${spec} capture`
     // Remove any prior cortex capture hook (idempotent: drop old token / old path forms).
     for (const grp of s.hooks.Stop) {
       if (Array.isArray(grp.hooks)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {