pqc-memory-mcp 1.0.0

package/docs/standalone-distribution.md

@@ -0,0 +1,92 @@
+# Standalone MCP distribution (open source)
+
+This repository serves **two audiences**:
+
+| Audience | What you use | Notes |
+|----------|----------------|-------|
+| **Contributors / Cryptic workspace** | The whole repo, including [`.cursor/`](../.cursor/) | Rules, hooks, and agent prompts are for development inside Cursor; they are not required to *run* the MCP server. |
+| **Open source consumers** | **`pqc-memory-mcp`** on npm, a **GitHub release zip**, or **`oss-bundle/pqc-memory-mcp/`** produced by **`npm run generate:standalone`** | Ships `dist/`, npm manifest from [`packaging/published-package.json`](../packaging/published-package.json), plus docs and optional `src/` for hackers. You still need a running **pqc-db** (or compatible) API, API key, and memory bucket. |
+
+The MCP server is a **client** of the pqc-db memory HTTP API. It does not start PostgreSQL, Qdrant, or Neo4j; those remain part of your pqc-db deployment.
+
+## Get the standalone folder
+
+### Option A – GitHub Release (recommended for end users)
+
+When maintainers publish a release, the workflow **OSS bundle** attaches a zip (e.g. `pqc-memory-mcp-standalone.zip`). Download and unzip.
+
+### Option B – Generate locally (maintainers)
+
+From the **repository root**:
+
+```bash
+npm install
+npm run generate:standalone
+```
+
+Output: **`oss-bundle/pqc-memory-mcp/`** (gitignored). That directory is what you **`npm publish`** (or **`npm pack`**) for the **`pqc-memory-mcp`** package. Alias: **`npm run bundle:oss`**.
+
+Flags passed through to the generator:
+
+- **`--no-lock`** — skip `npm install --package-lock-only` in the standalone folder (offline / CI speed).
+- **`--version=1.2.3`** — override **`version`** in the generated `package.json` (otherwise uses [`packaging/published-package.json`](../packaging/published-package.json)).
+
+### Option C – Clone the full repo
+
+Clone as usual, then **ignore** `.cursor/` if you only want to run the server. From the root: **`npm install`**, **`npm run build`**, configure your agent against **`dist/index.js`**, or run **`npm run generate:standalone`** and use **`oss-bundle/pqc-memory-mcp/`**.
+
+### Option D – npm / npx (no clone)
+
+Once **`pqc-memory-mcp`** is published to npm:
+
+```bash
+npm install -g pqc-memory-mcp
+# stdio MCP (most local agents):
+pqc-memory-mcp
+```
+
+Or let your agent download it on demand: **`npx -y pqc-memory-mcp`**.
+
+**Guided init (no manual JSON):** **`npx -y pqc-memory-mcp init`** prompts for **Cursor**, **Claude Code**, or **JetBrains Junie** and writes the right file (e.g. **`.cursor/mcp.json`**, **`.mcp.json`**, **`.junie/mcp/mcp.json`**, or the matching global path).
+
+**Other agents:** install into Cursor, Claude Code, etc. with Neon's [**add-mcp**](https://github.com/neondatabase/add-mcp), for example:
+
+```bash
+npx add-mcp "npx -y pqc-memory-mcp" -a cursor -y --name pqc-memory
+```
+
+Then edit the generated config and add **`env`**: `PQC_API_URL`, `PQC_API_KEY`, `PQC_BUCKET_ID`. See the [README](../README.md) section *Easiest install: add-mcp*.
+
+**HTTP MCP** (hosted / Streamable HTTP): run **`pqc-memory-mcp-http`** (or `npx -y pqc-memory-mcp-http`) with `PQC_TENANT_RESOLUTION_URL` and related variables from the README.
+
+## After you have the standalone folder
+
+1. **Install production dependencies**
+
+   ```bash
+   cd pqc-memory-mcp
+   npm ci --omit=dev
+   ```
+
+   Release zips and generated trees include **`dist/`**. To compile from **`src/`** yourself, install **`typescript`** in that tree and run **`npx tsc`** (the published npm tarball normally includes only **`files`** from `package.json`, not `src/`).
+
+2. **Configure environment** – Copy [.env.example](../.env.example) to `.env` or set variables in your MCP client. For Cursor stdio mode you need at least `PQC_API_URL`, `PQC_API_KEY`, and `PQC_BUCKET_ID`. See the main README for HTTP MCP and tenant-context variables.
+
+3. **Point your MCP client at** `dist/index.js` (stdio) or run **`npm run start:http`** for HTTP transport, as documented in the README.
+
+## What the generated standalone includes
+
+- **`package.json`** from [`packaging/published-package.json`](../packaging/published-package.json) (npm **`files`** control what actually lands on the registry)
+- **`dist/`** (built from this repo before generate), **`scripts/start.mjs`**, **`src/`**, **`docs/`**, **`tsconfig.json`**, **`.env.example`**, **`README.md`**, **`AGENTS.md`**, optional **`LICENSE*`** from repo root
+- **`package-lock.json`** when generate runs with network (omit with **`--no-lock`**)
+
+## What it excludes
+
+- `.cursor/` and other editor-only assets (they never leave the generator repo)
+- `node_modules/` and local secrets (`.env`)
+
+## Maintainer notes
+
+- Bump the **published** version in [`packaging/published-package.json`](../packaging/published-package.json) before tagging / npm publish.
+- **`npm run publish:npm`** (root) runs **`generate:standalone`** then **`npm publish`** inside **`oss-bundle/pqc-memory-mcp`**. The root **`package.json`** stays **`private`: true** so accidental **`npm publish`** at the repo root fails.
+- Add a **`LICENSE`** at the repo root when you choose a license; **`generate-standalone`** copies **`LICENSE*`** into the bundle if present.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "pqc-memory-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for pqc-db persistent memory — stdio or HTTP; works with Cursor, Claude Code, Codex, VS Code, JetBrains Junie, Zed, and other MCP hosts",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pqc-memory-mcp": "./dist/cli.js",
+    "pqc-memory-mcp-http": "./dist/http.js"
+  },
+  "files": [
+    "dist",
+    "scripts/start.mjs",
+    "README.md",
+    "AGENTS.md",
+    ".env.example",
+    "docs"
+  ],
+  "scripts": {
+    "start": "node scripts/start.mjs",
+    "start:stdio": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "init": "node dist/cli.js init",
+    "build": "node -e \"console.error('\\n  This package already includes dist/ — there is no compile step here.\\n\\n  To edit source and rebuild:\\n    git clone https://github.com/CascadiaTech/pqc-mcp-server.git\\n    cd pqc-mcp-server && npm install && npm run build && npm run generate:standalone\\n\\n  See the Maintainer guide in that repo README.\\n'); process.exit(1)\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "express": "^5.2.1",
+    "zod": "^3.22.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CascadiaTech/pqc-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CascadiaTech/pqc-mcp-server/issues"
+  },
+  "homepage": "https://github.com/CascadiaTech/pqc-mcp-server#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pqc-db",
+    "memory",
+    "cursor",
+    "stdio",
+    "claude",
+    "agent"
+  ]
+}

package/scripts/start.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * PaaS (Zeabur, etc.) usually runs `npm start`. Route to HTTP MCP when
+ * tenant resolution is configured; otherwise stdio MCP for local Cursor.
+ */
+const httpEntry = new URL("../dist/http.js", import.meta.url).href;
+const stdioEntry = new URL("../dist/index.js", import.meta.url).href;
+
+if (process.env.PQC_TENANT_RESOLUTION_URL) {
+  await import(httpEntry);
+} else {
+  await import(stdioEntry);
+}