@pragmatic-growth/memory-mcp 2.4.0 → 3.0.0

package/AGENTS.md

@@ -0,0 +1,15 @@
+# MCP Stdio Package Instructions
+
+## Package Role
+- `packages/mcp-stdio` is the stdio proxy CLI that bridges MCP clients to the HTTP server.
+- Entry point: `packages/mcp-stdio/src/index.ts` -> build output in `packages/mcp-stdio/dist/`.
+
+## Change Guidelines
+- Keep Node >= 18 compatibility and ESM (`"type": "module"`).
+- Use `zod` for input validation and keep CLI flags backward compatible.
+- If you change CLI behavior, update `packages/mcp-stdio/README.md`.
+- Any change to this package requires a version bump and a publish to npm.
+
+## Build & Test
+- Build: `pnpm --filter @pragmatic-growth/memory-mcp build`.
+- Run locally: `pnpm --filter @pragmatic-growth/memory-mcp dev`.

package/README.md

@@ -7,15 +7,15 @@ Stdio proxy for PG-Memory - connects stdio-based MCP clients to your PG-Memory H
 PG-Memory supports **two MCP transport modes**:
 
 ### 1. HTTP Transport (Direct)
-For clients that support HTTP/SSE transport (Claude Code, mcp-remote):
+For clients that support HTTP/SSE transport (Codex, Cursor, Claude Code):
 ```json
 {
   "mcpServers": {
     "pg-memory": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://your-server.up.railway.app/api/mcp"],
-      "env": {
-        "API_KEY": "your-api-key"
+      "url": "https://your-server.up.railway.app/api/mcp",
+      "headers": {
+        "X-API-Key": "your-clerk-api-key"
       }
     }
   }
@@ -31,7 +31,7 @@ For clients that only support stdio (Raycast, local tools):
   "command": "npx",
   "args": ["-y", "@pragmatic-growth/memory-mcp"],
   "env": {
-    "MCP_API_KEY": "your-api-key"
+    "CLERK_API_KEY": "your-api-key"
   }
 }
 ```
@@ -65,7 +65,7 @@ Includes all read-only tools PLUS write operations:
   "command": "npx",
   "args": ["-y", "@pragmatic-growth/memory-mcp"],
   "env": {
-    "MCP_API_KEY": "your-api-key-here"
+    "CLERK_API_KEY": "your-api-key-here"
   }
 }
 ```
@@ -79,7 +79,7 @@ Includes all read-only tools PLUS write operations:
   "command": "npx",
   "args": ["-y", "@pragmatic-growth/memory-mcp", "--full"],
   "env": {
-    "MCP_API_KEY": "your-api-key-here"
+    "CLERK_API_KEY": "your-api-key-here"
   }
 }
 ```
@@ -94,17 +94,17 @@ Then run directly:
 
 ```bash
 # Read-only mode (default)
-MCP_API_KEY=your-key memory-mcp
+CLERK_API_KEY=your-key memory-mcp
 
 # Full mode
-MCP_API_KEY=your-key memory-mcp --full
+CLERK_API_KEY=your-key memory-mcp --full
 ```
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `MCP_API_KEY` | Yes | API key for authentication |
+| `CLERK_API_KEY` | Yes | Clerk API key for authentication |
 | `MCP_SERVER_URL` | No | Custom server URL (default: production) |
 | `MCP_MODE` | No | Set to `full` to enable write operations |
 
@@ -191,7 +191,12 @@ For full mode to work:
 
 ## Changelog
 
-### v2.4.0 (Latest)
+### v3.0.0 (Latest)
+- Breaking: `CLERK_API_KEY` replaces `MCP_API_KEY`
+- Adds MCP protocol negotiation for 2025-11-25, 2025-06-18, 2025-03-26
+- Sends `MCP-Protocol-Version` on follow-up requests
+
+### v2.4.0
 - Changed default server URL to custom domain: `https://memory.pragmaticgrowth.com/api/mcp`
 - Simplified authentication to API key only (removed OAuth infrastructure)
 - Updated dependencies to latest versions
@@ -202,7 +207,7 @@ For full mode to work:
 - Added Knowledge Graph tools: `find_related`, `get_entities`, `search_entities`, `get_knowledge_graph`
 - Added Episodic Memory tools: `start_conversation`, `add_message`, `get_conversation`, `list_conversations`, `get_session_context`
 - Added Q&A tool: `add_question`
-- Updated to MCP Protocol 2025-11-25
+- Updated to MCP Protocol (supports 2025-11-25, 2025-06-18, 2025-03-26)
 
 ### v2.1.1
 - Initial public release with core knowledge tools

package/dist/index.d.ts

@@ -11,7 +11,7 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - Clerk API key for authentication (required)
+ *   CLERK_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
  *

package/dist/index.js

@@ -11,7 +11,7 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - Clerk API key for authentication (required)
+ *   CLERK_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
  *
@@ -29,15 +29,16 @@ const envMode = process.env.MCP_MODE?.toLowerCase();
 const isFullMode = hasFullFlag || envMode === 'full' || envMode === 'edit';
 // Configuration
 const SERVER_URL = process.env.MCP_SERVER_URL || 'https://memory.pragmaticgrowth.com/api/mcp';
-const API_KEY = process.env.MCP_API_KEY;
+const API_KEY = process.env.CLERK_API_KEY;
 if (!API_KEY) {
-    console.error('Error: MCP_API_KEY environment variable is required');
+    console.error('Error: CLERK_API_KEY environment variable is required');
     console.error('Get your Clerk API key from the Clerk Dashboard or app API Docs page');
     console.error('Set it in your MCP client configuration under "env"');
     process.exit(1);
 }
 // HTTP session management
 let sessionId = null;
+let negotiatedProtocolVersion = null;
 /**
  * Make an HTTP request to the remote MCP server.
  * Uses X-API-Key header for Clerk API key authentication.
@@ -50,6 +51,9 @@ async function callRemoteServer(method, params) {
     if (sessionId) {
         headers['Mcp-Session-Id'] = sessionId;
     }
+    if (negotiatedProtocolVersion && method !== 'initialize') {
+        headers['Mcp-Protocol-Version'] = negotiatedProtocolVersion;
+    }
     const body = {
         jsonrpc: '2.0',
         id: Date.now(),
@@ -76,14 +80,20 @@ async function callRemoteServer(method, params) {
  * Initialize connection to remote server.
  */
 async function initializeRemoteSession() {
-    await callRemoteServer('initialize', {
+    const result = await callRemoteServer('initialize', {
         protocolVersion: '2025-11-25',
         capabilities: {},
         clientInfo: {
             name: 'pg-memory-stdio',
-            version: '2.4.0',
+            version: '3.0.0',
         },
     });
+    if (typeof result === 'object' && result && 'protocolVersion' in result) {
+        const protocolVersion = result.protocolVersion;
+        if (protocolVersion) {
+            negotiatedProtocolVersion = protocolVersion;
+        }
+    }
 }
 /**
  * Create and start the stdio MCP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pragmatic-growth/memory-mcp",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Stdio proxy for PG-Memory - connects stdio-based MCP clients (Claude Desktop, Raycast) to your PG-Memory HTTP server using Clerk API key authentication. Supports both read-only and full edit modes.",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -11,7 +11,7 @@
  *   npx @pragmatic-growth/memory-mcp --edit      # Alias for --full
  *
  * Environment variables:
- *   MCP_API_KEY - Clerk API key for authentication (required)
+ *   CLERK_API_KEY - Clerk API key for authentication (required)
  *   MCP_SERVER_URL - Server URL (default: https://pg-memory-production.up.railway.app/api/mcp)
  *   MCP_MODE - Mode: 'readonly' (default) or 'full' for edit capabilities
  *
@@ -32,10 +32,10 @@ const isFullMode = hasFullFlag || envMode === 'full' || envMode === 'edit';
 
 // Configuration
 const SERVER_URL = process.env.MCP_SERVER_URL || 'https://memory.pragmaticgrowth.com/api/mcp';
-const API_KEY = process.env.MCP_API_KEY;
+const API_KEY = process.env.CLERK_API_KEY;
 
 if (!API_KEY) {
-  console.error('Error: MCP_API_KEY environment variable is required');
+  console.error('Error: CLERK_API_KEY environment variable is required');
   console.error('Get your Clerk API key from the Clerk Dashboard or app API Docs page');
   console.error('Set it in your MCP client configuration under "env"');
   process.exit(1);
@@ -43,6 +43,7 @@ if (!API_KEY) {
 
 // HTTP session management
 let sessionId: string | null = null;
+let negotiatedProtocolVersion: string | null = null;
 
 interface JsonRpcResponse {
   result?: {
@@ -65,6 +66,9 @@ async function callRemoteServer(method: string, params?: Record<string, unknown>
   if (sessionId) {
     headers['Mcp-Session-Id'] = sessionId;
   }
+  if (negotiatedProtocolVersion && method !== 'initialize') {
+    headers['Mcp-Protocol-Version'] = negotiatedProtocolVersion;
+  }
 
   const body = {
     jsonrpc: '2.0',
@@ -98,14 +102,20 @@ async function callRemoteServer(method: string, params?: Record<string, unknown>
  * Initialize connection to remote server.
  */
 async function initializeRemoteSession(): Promise<void> {
-  await callRemoteServer('initialize', {
+  const result = await callRemoteServer('initialize', {
     protocolVersion: '2025-11-25',
     capabilities: {},
     clientInfo: {
       name: 'pg-memory-stdio',
-      version: '2.4.0',
+      version: '3.0.0',
     },
   });
+  if (typeof result === 'object' && result && 'protocolVersion' in result) {
+    const protocolVersion = (result as { protocolVersion?: string }).protocolVersion;
+    if (protocolVersion) {
+      negotiatedProtocolVersion = protocolVersion;
+    }
+  }
 }
 
 /**