pqc-memory-mcp 1.0.0

package/.env.example

@@ -0,0 +1,47 @@
+# --- Stdio MCP (Cursor, Claude Code, Claude Desktop) ---
+PQC_API_URL=http://localhost:8081
+PQC_API_KEY=your-api-key-here
+PQC_BUCKET_ID=your-bucket-uuid-here
+
+# Optional: memory session TTL (minutes); also used as HTTP fallback if tenant-context omits session_ttl_minutes
+# PQC_SESSION_TTL=1440
+
+# --- HTTP MCP (remote connectors) — npm run start:http ---
+# Public pqc-api ORIGIN only (scheme + host + port). No path. e.g. https://crypticpqc.com or http://localhost:8081
+# MCP calls GET {origin}/api/v1/mcp/tenant-context
+# PQC_TENANT_RESOLUTION_URL=https://crypticpqc.com
+
+# Optional: must match pqc-api MCP_TENANT_SERVICE_API_KEY when that is set; sent as X-API-Key on tenant-context and POST /auth/mcp-exchange.
+# If pqc-api does not use MCP_TENANT_SERVICE_API_KEY, leave this unset.
+# PQC_MCP_SERVICE_API_KEY=
+
+# Auth0 → pqc-db JWT exchange (requires pqc-db POST /api/v1/auth/mcp-exchange). Omit = Bearer goes straight to tenant-context (pqc-db JWT only).
+# retry | 1 | true = same mode: tenant-context first, then mcp-exchange only if that returns 401. always = exchange first (best for Claude + Auth0 only).
+# PQC_MCP_AUTH0_EXCHANGE=always
+# PQC_MCP_AUTH0_EXCHANGE=true
+
+# Optional: listen port. On Zeabur/Railway/Render, PORT is set for you; otherwise default 8787.
+# PQC_MCP_HTTP_PORT=8787
+
+# Optional: Host header allowlist (comma-separated) when binding publicly
+# PQC_MCP_ALLOWED_HOSTS=mcp.example.com
+
+# OAuth protected-resource metadata (RFC 9728) — required for Claude connector discovery (well-known must not 404 in prod).
+# PQC_MCP_PUBLIC_URL = public origin of THIS MCP host only (no path), e.g. https://mcp.crypticpqc.com
+# PQC_MCP_AUTHORIZATION_SERVERS = OAuth issuer URL(s), comma-separated if multiple.
+#
+# Auth0: Dashboard → Settings → Domain → issuer is https://<Domain>/
+#   Example shape: https://dev-xxxxxxxx.us.auth0.com/
+#   If you use an Auth0 custom domain, use that as issuer (match the "iss" claim on access tokens).
+# PQC_MCP_PUBLIC_URL=https://mcp.example.com
+# PQC_MCP_AUTHORIZATION_SERVERS=https://dev-xxxxxxxx.us.auth0.com/
+#
+# RFC 9728 JSON field "resource" (default: {PQC_MCP_PUBLIC_URL}/mcp). If Auth0 API Identifier is the origin only
+# (e.g. https://mcp.crypticpqc.com) and Claude maps resource → audience, set this to match or Auth0 may return opaque tokens:
+# PQC_MCP_PRM_RESOURCE=https://mcp.crypticpqc.com
+
+# Verbose JSON logs to stderr: every HTTP hit, PRM, tenant-context, mcp-exchange, auth branches (no secrets; token SHA-256 prefix only).
+# PQC_MCP_DEBUG=1
+
+# DEV ONLY: treat any Bearer as env tenant (ignored when NODE_ENV=production). Requires PQC_API_* above.
+# PQC_TENANT_CONTEXT_MOCK=1

package/AGENTS.md

@@ -0,0 +1,13 @@
+## Learned User Preferences
+
+- Target one MCP codebase that works in Claude Code, Cursor, and remote Claude chat, not only a single local setup.
+- For a broadly usable hosted MCP, plan on OAuth plus DCR-friendly setup (or a custom-credentials variant that fits the IdP) and per-user tenant context instead of one shared process-global environment for all users.
+
+## Learned Workspace Facts
+
+- Encrypted org object upload and download in this stack go through the managed-key API only: `POST /api/v1/keys/managed/{key_id}/objects` (multipart with `file`, `bucket_id`, optional `filename`) and `GET /api/v1/keys/managed/{key_id}/objects/{object_id}`; do not use removed legacy paths such as `/api/v1/objects/upload` or `/api/v1/objects/{id}/download` for that flow.
+- For HTTP MCP with tenant resolution, set `PQC_TENANT_RESOLUTION_URL` to the public API origin only (no path, no trailing slash). Call `GET {origin}/api/v1/mcp/tenant-context` with `Authorization: Bearer` carrying a valid pqc-api access JWT; use the JSON body fields (for example `api_url`, `api_key`, `bucket_id`, and session TTL when present) for subsequent memory calls.
+- The Cursor MCP command can run the local `dist/index.js` bridge while environment variables still point `PQC_API_URL` (or equivalent) at a remote host; treating the process as local does not mean the backing API is local unless those vars target a local stack.
+- This repo root is the **generator** (`pqc-mcp-server`, `private` on npm). The publishable package is **`pqc-memory-mcp`**, produced under **`oss-bundle/pqc-memory-mcp/`** via **`npm run generate:standalone`** from [`packaging/published-package.json`](packaging/published-package.json). Do not `npm publish` from the repo root.
+- pqc-mcp-server is primarily a typed client to pqc-db’s REST API; heavier object storage and conversion logic is expected to stay in pqc-db or workers rather than duplicating upload or download paths in the MCP.
+- If pqc-memory MCP tools fail parsing JSON with errors such as unexpected token at position zero, the client often received HTML (login page, proxy error, or non-API response); check the configured API URL, API key and bucket, that `dist/` is rebuilt after code changes, and that the correct MCP server is attached in the active Cursor project.

package/README.md

@@ -0,0 +1,403 @@
+# PQC Memory MCP Server
+
+An MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that connects **any MCP-capable client**—IDEs, CLI agents, or hosted connectors—to your **pqc-db** memory API for persistent, org-scoped memory across sessions. **Cursor** is one supported host; the same **`pqc-memory-mcp`** package also works with **Claude Code**, **Codex**, **VS Code**, **JetBrains Junie**, **Zed**, and others that speak stdio or Streamable HTTP MCP (see [**add-mcp** supported agents](https://github.com/neondatabase/add-mcp#supported-agents)).
+
+**This GitHub repo (`pqc-mcp-server`) is the generator / dev workspace** (`private` on npm—do not publish from the root). The **npm package `pqc-memory-mcp`** is produced under **`oss-bundle/pqc-memory-mcp/`** via **`npm run generate:standalone`**. Publish only from that folder (or use **`npm run publish:npm`** from the repo root). Manifest template: [`packaging/published-package.json`](packaging/published-package.json) (bump **`version`** there before a release).
+
+**Consumers** use npm (`npx -y pqc-memory-mcp`), a GitHub release zip, or a clone; see [docs/standalone-distribution.md](docs/standalone-distribution.md). **Contributors** keep the full tree, including [`.cursor/`](.cursor/).
+
+
+# Quick run instructions
+- cd /path/to/pqc-mcp-server
+- run npm install
+- npm run build
+- npm run generate:standalone
+- cd oss-bundle && cd pqc-memory-mcp -- from here can run (npm run init) or
+- npm pack - generates: pqc-memory-mcp/pqc-memory-mcp-1.0.0.tgz
+- now take the tarball to a local workspace root in cursor, jetbrians, vscode. 
+- open a terminal in the workspace root and run the commands below
+- npm install /full/path/to/pqc-memory-mcp-1.0.0.tgz (npm install ./pqc-memory-mcp-1.0.0.tgz)
+- npx -y pqc-memory-mcp init
+- setup wizard takes over
+
+
+## Features
+
+- **Semantic Search** - Find memories by meaning, not just keywords
+- **Reflective Memory** - Intelligent synthesis using AI to answer questions from your memory bank
+- **Knowledge Graph** - Explore entities and relationships extracted from memories
+- **Outcome Tracking** - Tag memories as success/failure to improve future recommendations
+- **Mental Models** - Pre-computed knowledge summaries
+- **Strategies** - Learned reasoning patterns from successful outcomes
+- **Conversation Summaries** - Save important conversations for future reference
+
+## Prerequisites
+
+1. **pqc-db running** - The API should be accessible (default: `http://localhost:8081`)
+2. **API Key** - Create one via the pqc-db dashboard or API
+3. **Bucket** - Create a memory bucket in pqc-db for this agent or team
+
+## Guided setup: Cursor, Claude Code, or Junie (no manual JSON)
+
+Same idea as [Agentation’s `agentation-mcp init`](https://www.agentation.com/install): run a short wizard; it **writes or merges** `mcpServers` with **`command`**, **`args`**, and **`PQC_*`** env.
+
+```bash
+npx -y pqc-memory-mcp init
+```
+
+(`setup` is an alias.) You pick the **client** and **scope**:
+
+| Client | Project scope | User (global) scope |
+|--------|---------------|----------------------|
+| **Cursor** | `<project>/.cursor/mcp.json` | `~/.cursor/mcp.json` |
+| **Claude Code** | `<project>/.mcp.json` | `~/.claude.json` ([docs](https://code.claude.com/docs/en/mcp)) |
+| **JetBrains Junie** | `<project>/.junie/mcp/mcp.json` | `~/.junie/mcp/mcp.json` ([docs](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html)) |
+
+Then paste URL / API key / bucket, and choose **npm `npx`** vs **local `node …/cli.js`**. Restart the IDE or CLI and confirm MCP (Cursor: Settings → Tools & MCP; Claude Code / Junie: **`/mcp`**).
+
+From a git clone of this repo (before publish):
+
+```bash
+npm install && npm run build && node dist/cli.js init
+```
+
+## Easiest install: add-mcp (optional)
+
+Use [**add-mcp**](https://github.com/neondatabase/add-mcp) from Neon: `npx add-mcp …` registers this server in one shot for **Cursor**, **Claude Code**, **Codex**, **VS Code**, and [many other hosts](https://github.com/neondatabase/add-mcp#supported-agents) (run `npx add-mcp list-agents`). Use **`-a <agent>`** to target one client, or omit it for detection. Local npm packages always run over **stdio**; the string you pass is the command your host invokes.
+
+The published package is **`pqc-memory-mcp`** ([npm](https://www.npmjs.com/package/pqc-memory-mcp)); source lives in [**pqc-mcp-server**](https://github.com/CascadiaTech/pqc-mcp-server) on GitHub.
+
+```bash
+# Interactive: detect agents in the current project
+npx add-mcp "npx -y pqc-memory-mcp" --name pqc-memory
+
+# Example: Cursor — project .cursor/mcp.json, no prompts
+npx add-mcp "npx -y pqc-memory-mcp" -a cursor -y --name pqc-memory
+
+# Example: Cursor — global ~/.cursor/mcp.json
+npx add-mcp "npx -y pqc-memory-mcp" -g -a cursor -y --name pqc-memory
+
+# Example: Claude Code only (see add-mcp for other -a names)
+npx add-mcp "npx -y pqc-memory-mcp" -a claude-code -y --name pqc-memory
+
+# Register all agents add-mcp supports, global configs
+npx add-mcp "npx -y pqc-memory-mcp" -g --all -y --name pqc-memory
+```
+
+**After `add-mcp`:** if you did **not** use **`npx pqc-memory-mcp init`**, you must still add **`env`** (`PQC_API_URL`, `PQC_API_KEY`, `PQC_BUCKET_ID`) to the config it wrote—or run **`npx -y pqc-memory-mcp init`** instead and skip `add-mcp` for Cursor.
+
+**Before the package is on npm:** point at a built **`dist/index.js`** (from this repo or from the generated standalone):
+
+```bash
+npm run generate:standalone
+npx add-mcp "node /absolute/path/to/pqc-mcp-server/oss-bundle/pqc-memory-mcp/dist/index.js" -a claude-code -y --name pqc-memory
+```
+
+(or use `.../pqc-mcp-server/dist/index.js` right after **`npm run build`**). Swap **`-a`** for your client. Then add the same **`env`** block in that client’s config.
+
+**Manual config** (stdio MCP) if you set up the host yourself—the **exact file and JSON shape** depend on the client (Cursor uses `mcpServers`; others use TOML or different keys). Conceptually you need **`command`**, **`args`**, and **`env`**:
+
+```json
+{
+  "mcpServers": {
+    "pqc-memory": {
+      "command": "npx",
+      "args": ["-y", "pqc-memory-mcp"],
+      "env": {
+        "PQC_API_URL": "http://localhost:8081",
+        "PQC_API_KEY": "your-api-key",
+        "PQC_BUCKET_ID": "your-bucket-uuid"
+      }
+    }
+  }
+}
+```
+
+*(Example shape compatible with Cursor-style **`mcp.json`**; translate for your tool’s docs.)*
+
+**Tie-in:** Put real values in **`env`**, **restart the MCP host** (IDE, CLI session, or connector) so it reloads servers, then invoke a memory tool—the first call should reach your pqc-db API using this server’s session flow.
+
+**Maintainers:** full **change → regenerate → test → release** flow is in [Maintainer guide](#maintainer-guide-develop-regenerate-test-release) below.
+
+**Git clone** (no npm registry): use the [standalone bundle](docs/standalone-distribution.md) or clone this repo, then follow **Setup** below.
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+git clone https://github.com/CascadiaTech/pqc-mcp-server.git
+cd pqc-mcp-server
+npm install
+```
+
+### 2. Build
+
+```bash
+npm run build
+```
+
+### 3. Configure your MCP client
+
+Point the host at **`dist/index.js`** (stdio) with **`PQC_API_*`** env vars. Example for **Cursor** (`~/.cursor/mcp.json` or project **`.cursor/mcp.json`**):
+
+```json
+{
+  "mcpServers": {
+    "pqc-memory": {
+      "command": "node",
+      "args": ["/path/to/pqc-mcp-server/dist/index.js"],
+      "env": {
+        "PQC_API_URL": "http://localhost:8081",
+        "PQC_API_KEY": "your-api-key",
+        "PQC_BUCKET_ID": "your-bucket-uuid"
+      }
+    }
+  }
+}
+```
+
+Other clients: use their documented MCP location and field names (often the same **`command` / `args` / `env`** idea).
+
+### 4. Restart the client
+
+Restart the IDE or agent (or reload MCP) so it picks up the new server.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Semantic search across memories |
+| `memory_reflect` | Intelligent synthesis with sources |
+| `memory_write` | Save new memory |
+| `memory_graph_entities` | List known entities |
+| `memory_graph_related` | Find related entities |
+| `memory_graph_memories` | Find memories by entity |
+| `memory_tag_outcome` | Mark memory as success/failure |
+| `memory_mental_models_list` | List mental models |
+| `memory_mental_model_get` | Get mental model details |
+| `memory_mental_model_create` | Create new mental model |
+| `memory_mental_model_refresh` | Refresh mental model |
+| `memory_strategies_list` | List learned strategies |
+| `memory_strategy_get` | Get strategy details |
+| `memory_save_summary` | Save conversation summary |
+| `memory_batch_write` | Write multiple memories |
+| `object_upload` | Encrypted upload via managed Kyber key (`POST .../keys/managed/{key_id}/objects`) |
+| `object_download` | Decrypted download via managed key (`GET .../objects/{object_id}`) |
+| `object_list` | List org objects (`GET /objects`, optional `bucket`) |
+| `object_get` | Object metadata (`GET /objects/{id}`) |
+
+See [docs/mcp-org-object-storage.md](docs/mcp-org-object-storage.md) for the API contract.
+
+## Usage examples
+
+In any connected MCP client’s chat:
+
+- "Search my memories for authentication patterns"
+- "What do I know about this project's testing approach?"
+- "Remember that I prefer TypeScript over JavaScript"
+- "Save this conversation - we fixed the database migration issue"
+
+## Remote HTTP MCP (Streamable HTTP)
+
+For clients that only support **HTTP** (e.g. Claude.ai custom connectors), run the second entrypoint. Each MCP request carries an `Authorization: Bearer <access_token>` header. The HTTP server calls **pqc-api** once per cached tenant window:
+
+`GET {PQC_TENANT_RESOLUTION_URL}/api/v1/mcp/tenant-context`
+
+Alignment with **pqc-api** (see [docs/pqc-api-tenant-context-go.md](docs/pqc-api-tenant-context-go.md)):
+
+| MCP env | Value |
+|--------|--------|
+| **`PQC_TENANT_RESOLUTION_URL`** | **Public API origin only** — no path, no trailing slash required, e.g. `https://crypticpqc.com` or `http://localhost:8081`. Same host you use for `/api/v1/...`. (Extra paths on this env are stripped to the origin.) |
+| Bearer token | With **`PQC_MCP_AUTH0_EXCHANGE` unset:** pqc-api **access JWT** only. With **`retry`** or **`always`:** Claude’s **Auth0 access JWT** is exchanged via **`POST /api/v1/auth/mcp-exchange`**, then **`tenant-context`** uses the minted pqc-db JWT (see [docs/mcp-auth0-exchange-contract.md](docs/mcp-auth0-exchange-contract.md)). |
+
+After a **200**, this server drives **all** memory traffic from the JSON body (`api_url`, `api_key`, `bucket_id`, optional `session_ttl_minutes`). It does **not** use `PQC_API_URL` / `PQC_API_KEY` / `PQC_BUCKET_ID` for HTTP mode (those remain for **stdio** and for **`PQC_TENANT_CONTEXT_MOCK`** only).
+
+**Optional service key (both sides must match):**
+
+| MCP | pqc-api |
+|-----|--------|
+| `PQC_MCP_SERVICE_API_KEY` | `MCP_TENANT_SERVICE_API_KEY` (same string) |
+
+If set on pqc-api, MCP sends **`X-API-Key`** on **`tenant-context`** and **`mcp-exchange`**. If pqc-api does **not** require it, leave both unset (otherwise those routes return **401**).
+
+Build and start:
+
+```bash
+npm run build
+export PQC_TENANT_RESOLUTION_URL="https://crypticpqc.com"
+npm run start:http
+```
+
+Point the connector at **`POST https://your-mcp-host/mcp`**.
+
+**Health checks (for load balancers or clicking the host in a browser):**
+
+- `GET https://your-mcp-host/` — short JSON + links  
+- `GET /health` or `GET /healthz` — minimal `{ "status": "ok", ... }`  
+- `GET /mcp` — **200** JSON explaining that MCP uses **POST** (opening `/mcp` in a browser is not an error)
+
+**Optional OAuth discovery:** set `PQC_MCP_PUBLIC_URL` and `PQC_MCP_AUTHORIZATION_SERVERS` (comma-separated issuer URLs) to expose [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata at `/.well-known/oauth-protected-resource/mcp`.
+
+**Cross-domain auth (Cryptic PQC):** see [docs/crypticpqc-cross-domain-auth.md](docs/crypticpqc-cross-domain-auth.md) for how **`crypticpqc.com`**, **`app.crypticpqc.com`**, **`mcp.crypticpqc.com`**, and **`crypto.crypticpqc.com`** should share Auth0, tokens, and `tenant-context`. When pqc-db ships **`POST /api/v1/auth/mcp-exchange`**, see [docs/mcp-auth0-exchange-contract.md](docs/mcp-auth0-exchange-contract.md) for the request/response contract (MCP will call exchange, then `tenant-context`). Spec vs implementation: [docs/mcp-authorization-spec-alignment.md](docs/mcp-authorization-spec-alignment.md).
+
+**Local dev without tenant-context:** set `PQC_TENANT_CONTEXT_MOCK=1` and the usual `PQC_API_*` env vars; **any** Bearer maps to that env tenant (ignored when `NODE_ENV=production`).
+
+## Maintainer guide: develop, regenerate, test, release
+
+This section is for people working in **`pqc-mcp-server`** (this repo). End users install **`pqc-memory-mcp`** from npm or a release zip—they do not run these steps unless they clone.
+
+### What lives where
+
+| Path | Role |
+|------|------|
+| **`src/`**, **`package.json` (root)** | Author changes here. Root is **`private`: true** — never **`npm publish`** from repo root. |
+| **`packaging/published-package.json`** | The **published** package name, version, `bin`, `files`, and runtime **`dependencies`**. Bump **`version`** here before each npm release. |
+| **`oss-bundle/pqc-memory-mcp/`** | **Generated** tree: what you **`npm pack`** / **`npm publish`** and what the GitHub Action zips. Gitignored; recreated by **`generate:standalone`**. |
+
+### Day-to-day: change code, rebuild, regenerate
+
+**Run these commands from the `pqc-mcp-server` repo root**, not from **`oss-bundle/pqc-memory-mcp`** or an extracted npm tarball. The published package ships **`dist/`** pre-built; `npm run build` there only prints where to go (`npm run build` in the generator repo compiles **`src/`**).
+
+1. **`git pull`** (if using git) and **`npm install`**.
+
+2. Edit **`src/`** (and **`packaging/published-package.json`** if metadata changes).
+
+3. **Typecheck and compile:**
+   ```bash
+   npm run typecheck
+   npm run build
+   ```
+
+4. **Regenerate the standalone folder** (copies fresh **`dist/`**, docs, manifest from packaging, etc.):
+   ```bash
+   npm run generate:standalone
+   ```
+   - Offline / skip lockfile refresh inside the bundle:  
+     `npm run build && node scripts/generate-standalone.mjs --no-lock`
+   - One-off version override for the generated **`package.json`**:  
+     `npm run build && node scripts/generate-standalone.mjs --version=1.2.3`
+
+5. **Automated smoke test** (what consumers get from the registry):
+   ```bash
+   npm run verify:pack
+   ```
+   This runs **`generate:standalone`**, then **`npm pack`** inside **`oss-bundle/pqc-memory-mcp`**, installs that `.tgz` in a temp project, and checks bins + missing-env error + stdio startup line.
+
+### Local testing (manual, like “install my own package”)
+
+**A. Tarball install (mirrors npm)**
+
+```bash
+cd oss-bundle/pqc-memory-mcp
+npm pack
+mkdir -p /tmp/pqc-smoke && cd /tmp/pqc-smoke
+npm init -y
+npm install /absolute/path/to/oss-bundle/pqc-memory-mcp/pqc-memory-mcp-x.y.z.tgz
+export PQC_API_URL="https://your-api-origin"
+export PQC_API_KEY="your-key"
+export PQC_BUCKET_ID="your-bucket-uuid"
+./node_modules/.bin/pqc-memory-mcp
+```
+Expect **`[pqc-memory] Server started (stdio)`** on stderr. Use **Ctrl+C** to stop.  
+`export VAR=value` must have **no space** around **`=`**.
+
+**B. Guided `init` wizard** (from repo, before publish):
+
+```bash
+npm run init
+```
+(or **`npm run build && node dist/cli.js init`**) — picks Cursor / Claude Code / Junie and writes the right **`mcp.json`**.
+
+**C. Point Cursor at a local build**
+
+- After **`npm run build`**: **`command`** = **`node`**, **`args`**: **`["/absolute/path/to/pqc-mcp-server/dist/cli.js"]`**, plus **`env`**.  
+- Or after **`generate:standalone`**: use **`…/oss-bundle/pqc-memory-mcp/dist/cli.js`**.
+
+### Release: version, verify, publish, GitHub
+
+1. **Version** — edit **`version`** in **`packaging/published-package.json`** (semantic versioning).
+
+2. **Verify from clean generation:**
+   ```bash
+   npm run verify:pack
+   ```
+
+3. **Dry-run the publish tarball** (optional):
+   ```bash
+   npm run pack:publish
+   ```
+   Inspect **`oss-bundle/pqc-memory-mcp/pqc-memory-mcp-*.tgz`**.
+
+4. **Publish to npm** (requires `npm login` / token and rights to the package name):
+   ```bash
+   npm run publish:npm
+   ```
+   Equivalent to:
+   ```bash
+   npm run generate:standalone
+   cd oss-bundle/pqc-memory-mcp
+   npm publish --access public
+   ```
+   Do **not** run **`npm publish`** in the repo root (it is **`private`**).
+
+5. **Git** — commit, tag (e.g. **`v1.2.3`** matching **`packaging/published-package.json`**), push. The **OSS bundle** workflow (`.github/workflows/oss-bundle.yml`) can build a zip on **release**; attach the artifact or **`pqc-memory-mcp-standalone.zip`** from CI as needed.
+
+### Dev commands (watch mode)
+
+```bash
+npm run dev          # stdio server, tsx watch
+npm run dev:http     # HTTP entry, tsx watch
+```
+
+### `npm start` (Zeabur, Railway, Docker)
+
+- If **`PQC_TENANT_RESOLUTION_URL`** is set → runs **HTTP** MCP (`dist/http.js`).
+- Otherwise → runs **stdio** MCP (`dist/index.js`, needs `PQC_API_*`).
+
+Use **`npm run start:http`** or **`npm run start:stdio`** to force one mode regardless of env.
+
+## Environment Variables
+
+### Stdio (local MCP clients)
+
+Local **stdio** transport: used by most editor and CLI integrations (e.g. Cursor, Claude Code, Codex, Junie, Zed—whatever your host supports).
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PQC_API_URL` | Yes | pqc-db API URL |
+| `PQC_API_KEY` | Yes | Your API key |
+| `PQC_BUCKET_ID` | Yes | Bucket UUID for memories |
+| `PQC_SESSION_TTL` | No | Session TTL in minutes (default: 1440) |
+
+### HTTP MCP
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PQC_TENANT_RESOLUTION_URL` | Yes | **pqc-api public origin only** (e.g. `https://crypticpqc.com`) for `GET /api/v1/mcp/tenant-context` |
+| `PQC_MCP_HTTP_PORT` | No | Listen port (default: 8787) |
+| `PQC_MCP_SERVICE_API_KEY` | No | If set, sent as `X-API-Key` on `tenant-context` and `mcp-exchange`; must equal pqc-api **`MCP_TENANT_SERVICE_API_KEY`** when that is enabled |
+| `PQC_MCP_AUTH0_EXCHANGE` | No | `retry` / `1` / `true` = exchange on 401; `always` = always call `mcp-exchange` first for Auth0 JWT. See [mcp-auth0-exchange-contract.md](docs/mcp-auth0-exchange-contract.md) |
+| `PQC_MCP_DEBUG` | No | Set to `1` for JSON debug lines on stderr: HTTP hits, PRM, `tenant-context`, `mcp-exchange`, auth branches (no secrets; inbound token fingerprint only). Disable after troubleshooting. |
+| `PQC_SESSION_TTL` | No | Fallback if tenant-context **200** omits `session_ttl_minutes` (pqc-api often returns **1440**) |
+| `PQC_MCP_ALLOWED_HOSTS` | No | Comma-separated `Host` allowlist (DNS rebinding protection) |
+| `PQC_MCP_PUBLIC_URL` | No | Public origin for OAuth PRM (e.g. `https://mcp.example.com`) |
+| `PQC_MCP_AUTHORIZATION_SERVERS` | No | Comma-separated issuer URLs (with `PQC_MCP_PUBLIC_URL`, serves PRM) |
+| `PQC_MCP_PRM_RESOURCE` | No | Override RFC 9728 `resource` in PRM (default `{PUBLIC_URL}/mcp`). Set to match Auth0 **API Identifier** if clients map `resource` → `audience` and you otherwise get **opaque** tokens. |
+| `PQC_TENANT_CONTEXT_MOCK` | No | Set to `1` for dev-only env-based tenant (see above) |
+
+## Architecture
+
+```
+MCP host (IDE, CLI agent, or HTTP connector)
+    ↓ MCP (stdio or Streamable HTTP)
+pqc-memory-mcp
+    ↓ HTTP + session token
+pqc-db API
+    ↓
+PostgreSQL + Qdrant + Neo4j
+```
+
+**Streamable HTTP** uses the same tools; the HTTP entry resolves **Bearer → tenant** via pqc-db before opening a memory session per cached tenant runtime.
+
+The stdio server maintains a persistent session with pqc-db for one configured bucket. The HTTP server caches **`TenantRuntime`** (client + session manager) per bearer hash with LRU eviction.

package/dist/auth/tenant-verifier.d.ts

@@ -0,0 +1,18 @@
+import type { TenantContext } from "../tenant.js";
+/** Shapes returned by verifyAccessToken; extended fields for pqc-mcp. */
+export type TenantAuthInfo = {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    tenantContext: TenantContext;
+    rawToken: string;
+};
+/**
+ * MCP SDK AccessTokenVerifier: resolves pqc-db tenant context for a bearer token.
+ * When PQC_MCP_AUTH0_EXCHANGE is set, calls POST /api/v1/auth/mcp-exchange for Auth0 JWTs (see docs).
+ */
+export declare function createPqcTenantVerifier(resolutionBaseUrl: string | undefined): {
+    verifyAccessToken(token: string): Promise<TenantAuthInfo>;
+};
+//# sourceMappingURL=tenant-verifier.d.ts.map

package/dist/auth/tenant-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-verifier.d.ts","sourceRoot":"","sources":["../../src/auth/tenant-verifier.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAiLF;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS;6BAM1C,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;EAgFlE"}