persistq 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2025-12-06
+
+### Added
+- **GitHub Copilot CLI Support**: Full compatibility with GitHub Copilot CLI MCP integration
+- Global error handlers for uncaught exceptions and unhandled promise rejections
+- Enhanced logging with configuration details on startup
+- Protocol version logging (supports 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
+- Detailed error logging for tool and resource operations
+- Enhanced error messages with HTTP status codes and response data
+- Comprehensive README documentation for GitHub Copilot CLI setup
+
+### Changed
+- Updated `@modelcontextprotocol/sdk` from `^1.20.2` to `^1.24.0`
+- Improved error handling with structured stderr logging
+- Enhanced startup logging with environment variable status
+- Updated README with Copilot CLI configuration instructions
+- Added MCP Inspector testing instructions
+
+### Fixed
+- All logging now correctly outputs to stderr (stdout reserved for MCP protocol only)
+- Enhanced error context for better debugging
+
+### Notes
+- **Breaking Changes**: None - fully backward compatible with Claude Code
+- **GitHub Copilot CLI**: Only supports MCP tools (not resources) - this is a Copilot limitation, not a package limitation
+- **Claude Code**: Continues to support both tools and resources
+
+## [1.0.0] - 2024-11-29
+
+### Added
+- Initial release
+- MCP Server implementation for PersistQ
+- 4 MCP tools: `add_memory`, `search_memory`, `list_memories`, `get_memory_stats`
+- 2 MCP resources: `persistq://memories/all`, `persistq://stats`
+- Claude Code integration support
+- Stdio transport for MCP communication
+- Environment variable configuration (PERSISTQ_URL, PERSISTQ_API_KEY, PERSISTQ_TOPIC)
+- Comprehensive README with setup instructions
+
+[1.1.0]: https://github.com/yourusername/persistq/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/yourusername/persistq/releases/tag/v1.0.0

package/README.md

@@ -1,117 +1,155 @@
-# PersistQ MCP Server
-
-MCP (Model Context Protocol) server for PersistQ - enabling persistent memory management for Claude Code and other AI tools.
-
-## Overview
-
-PersistQ MCP Server provides a bridge between AI assistants (like Claude Code) and the PersistQ memory management system. It allows AI tools to:
-
-- Store and retrieve memories
-- Search across stored content
-- Organize memories by topics/projects
-- Access persistent memory statistics
-
-## Installation
-
-```bash
-cd mcp-server
-npm install
-```
-
-## Configuration
-
-The server can be configured using environment variables:
-
-- `PERSISTQ_URL`: URL of the PersistQ HTTP server (default: `http://localhost:3000`)
-- `PERSISTQ_API_KEY`: API key for authentication (default: auto-generated)
-- `PERSISTQ_TOPIC`: Default topic for memories (default: `ClaudeConversations`)
-
-## Usage
-
-### Starting the Server
-
-```bash
-npm start
-```
-
-### Available Tools
-
-The MCP server exposes the following tools:
-
-#### 1. add_memory
-Add a new memory to PersistQ.
-
-**Parameters:**
-- `text` (required): The memory content to store
-- `topic` (optional): Category or topic for this memory
-- `metadata` (optional): Additional metadata object
-
-#### 2. search_memory
-Search memories by keyword or topic.
-
-**Parameters:**
-- `query` (required): Search query or keyword
-- `topic` (optional): Filter by topic
-- `limit` (optional): Maximum number of results (default: 10)
-
-#### 3. get_memory_stats
-Get statistics about stored memories.
-
-**Parameters:** None
-
-#### 4. list_memories
-List memories with optional filtering.
-
-**Parameters:**
-- `project` (optional): Filter by project/tag name
-- `limit` (optional): Maximum results (default: 10)
-- `offset` (optional): Offset for pagination (default: 0)
-
-### Available Resources
-
-The server provides the following resources:
-
-- `persistq://memories/all`: List of all stored memories
-- `persistq://stats`: Overview of memory storage statistics
-
-## Integration with Claude Code
-
-Add to your Claude Code MCP configuration (`~/.claude/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "persistq": {
-      "command": "node",
-      "args": ["D:/Projects/MemoryHub-Monorepo/mcp-server/pq-mcp-server.js"],
-      "env": {
-        "PERSISTQ_URL": "http://localhost:3000",
-        "PERSISTQ_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
-```
-
-## Architecture
-
-```
-Claude Code / AI Tool
-    ↓
-MCP Protocol (stdio)
-    ↓
-pq-mcp-server.js
-    ↓
-HTTP → PersistQ Server (port 3000)
-    ↓
-Database Storage
-```
-
-## Requirements
-
-- Node.js 16+
-- PersistQ HTTP server running on port 3000
-
-## License
-
-MIT
+# PersistQ MCP Server
+
+MCP (Model Context Protocol) server for PersistQ - enabling persistent memory management for Claude Code and other AI tools.
+
+## Overview
+
+PersistQ MCP Server provides a bridge between AI assistants (like Claude Code) and the PersistQ memory management system. It allows AI tools to:
+
+- Store and retrieve memories
+- Search across stored content
+- Organize memories by topics/projects
+- Access persistent memory statistics
+
+## Installation
+
+```bash
+cd mcp-server
+npm install
+```
+
+## Configuration
+
+The server can be configured using environment variables:
+
+- `PERSISTQ_URL`: URL of the PersistQ HTTP server (default: `http://localhost:3000`)
+- `PERSISTQ_API_KEY`: API key for authentication (default: auto-generated)
+- `PERSISTQ_TOPIC`: Default topic for memories (default: `ClaudeConversations`)
+
+## Usage
+
+### Starting the Server
+
+```bash
+npm start
+```
+
+### Available Tools
+
+The MCP server exposes the following tools:
+
+#### 1. add_memory
+Add a new memory to PersistQ.
+
+**Parameters:**
+- `text` (required): The memory content to store
+- `topic` (optional): Category or topic for this memory
+- `metadata` (optional): Additional metadata object
+
+#### 2. search_memory
+Search memories by keyword or topic.
+
+**Parameters:**
+- `query` (required): Search query or keyword
+- `topic` (optional): Filter by topic
+- `limit` (optional): Maximum number of results (default: 10)
+
+#### 3. get_memory_stats
+Get statistics about stored memories.
+
+**Parameters:** None
+
+#### 4. list_memories
+List memories with optional filtering.
+
+**Parameters:**
+- `project` (optional): Filter by project/tag name
+- `limit` (optional): Maximum results (default: 10)
+- `offset` (optional): Offset for pagination (default: 0)
+
+### Available Resources
+
+The server provides the following resources:
+
+- `persistq://memories/all`: List of all stored memories
+- `persistq://stats`: Overview of memory storage statistics
+
+## Integration with Claude Code
+
+Add to your Claude Code MCP configuration (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "persistq": {
+      "command": "node",
+      "args": ["D:/Projects/MemoryHub-Monorepo/mcp-server/pq-mcp-server.js"],
+      "env": {
+        "PERSISTQ_URL": "http://localhost:3000",
+        "PERSISTQ_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Integration with GitHub Copilot CLI
+
+Add to your Copilot CLI MCP configuration (`~/.copilot/mcp-config.json` or `~/.config/mcp-config.json`):
+
+```json
+{
+  "mcpServers": {
+    "persistq": {
+      "command": "node",
+      "args": ["D:/Projects/MemoryHub-Monorepo/mcp-server/pq-mcp-server.js"],
+      "env": {
+        "PERSISTQ_URL": "http://localhost:3000",
+        "PERSISTQ_API_KEY": "${PERSISTQ_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Important Notes:**
+- GitHub Copilot CLI currently **only supports MCP tools** (not resources or prompts)
+- The following 4 tools are available in Copilot CLI:
+  - `add_memory` - Store new memories
+  - `search_memory` - Search stored memories
+  - `get_memory_stats` - Get memory statistics
+  - `list_memories` - List memories with filtering
+- Resources (`persistq://memories/all`, `persistq://stats`) are only available in Claude Code
+
+### Testing with MCP Inspector
+
+Validate the server using the official MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node D:/Projects/MemoryHub-Monorepo/mcp-server/pq-mcp-server.js
+```
+
+This will open a web interface to test protocol compliance, tool execution, and error handling.
+
+## Architecture
+
+```
+Claude Code / AI Tool
+    ↓
+MCP Protocol (stdio)
+    ↓
+pq-mcp-server.js
+    ↓
+HTTP → PersistQ Server (port 3000)
+    ↓
+Database Storage
+```
+
+## Requirements
+
+- Node.js 16+
+- PersistQ HTTP server running on port 3000
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "persistq",
-  "version": "1.0.0",
-  "description": "MCP Server for PersistQ - Persistent Memory Management for Claude Code and AI assistants",
+  "version": "1.1.0",
+  "description": "MCP Server for PersistQ - Persistent Memory Management for Claude Code, GitHub Copilot CLI, and AI assistants",
   "main": "pq-mcp-server.js",
   "type": "commonjs",
   "bin": {
@@ -12,7 +12,7 @@
     "dev": "node pq-mcp-server.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.2",
+    "@modelcontextprotocol/sdk": "^1.24.0",
     "axios": "^1.6.0"
   },
   "keywords": [
@@ -21,10 +21,14 @@
     "mcp-server",
     "memory",
     "claude",
+    "copilot",
+    "github-copilot",
     "ai",
     "model-context-protocol",
     "claude-code",
-    "memory-management"
+    "memory-management",
+    "persistent-memory",
+    "ai-memory"
   ],
   "author": "",
   "license": "MIT",
@@ -33,6 +37,7 @@
   },
   "files": [
     "pq-mcp-server.js",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ]
 }

package/pq-mcp-server.js

@@ -1,244 +1,278 @@
-#!/usr/bin/env node
-/**
- * PersistQ MCP Server (Stdio Transport)
- * Uses official @modelcontextprotocol/sdk for stdio communication with Claude Code
- * Connects to PersistQ HTTP server on port 3000
- */
-
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema
-} = require('@modelcontextprotocol/sdk/types.js');
-const axios = require('axios');
-
-const PERSISTQ_URL = process.env.PERSISTQ_URL || 'http://localhost:3000';
-const API_KEY = process.env.PERSISTQ_API_KEY || 'pq_9df422f134ef9ec93e8337dd5bde0540dfd3d0de714e6e00379f3f7f174cfdff';
-const TOPIC = process.env.PERSISTQ_TOPIC || 'ClaudeConversations';
-
-// Create MCP server
-const server = new Server(
-  {
-    name: 'persistq-mcp-server',
-    version: '1.0.0'
-  },
-  {
-    capabilities: {
-      tools: {},
-      resources: {}
-    }
-  }
-);
-
-// Tool: list_tools
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: [
-    {
-      name: 'add_memory',
-      description: 'Add a new memory to PersistQ',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          text: { type: 'string', description: 'The memory content to store' },
-          topic: { type: 'string', description: 'Category or topic for this memory', default: TOPIC },
-          metadata: { type: 'object', description: 'Additional metadata' }
-        },
-        required: ['text']
-      }
-    },
-    {
-      name: 'search_memory',
-      description: 'Search memories by keyword or topic',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: 'Search query or keyword' },
-          topic: { type: 'string', description: 'Filter by topic' },
-          limit: { type: 'number', description: 'Maximum results', default: 10 }
-        },
-        required: ['query']
-      }
-    },
-    {
-      name: 'get_memory_stats',
-      description: 'Get statistics about stored memories',
-      inputSchema: {
-        type: 'object',
-        properties: {}
-      }
-    },
-    {
-      name: 'list_memories',
-      description: 'List memories with optional filtering by project/tag',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          project: { type: 'string', description: 'Filter by project/tag name' },
-          limit: { type: 'number', description: 'Maximum results', default: 10 },
-          offset: { type: 'number', description: 'Offset for pagination', default: 0 }
-        }
-      }
-    }
-  ]
-}));
-
-// Tool: call_tool
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    switch (name) {
-      case 'add_memory': {
-        const response = await axios.post(`${PERSISTQ_URL}/api/memory`, {
-          content: args.text,
-          project: args.topic || TOPIC,
-          metadata: args.metadata || {}
-        }, {
-          headers: {
-            'Authorization': `Bearer ${API_KEY}`,
-            'Content-Type': 'application/json'
-          }
-        });
-        const memoryId = response.data.data?.memoryId || response.data.memory?.id || response.data.id || 'OK';
-        return {
-          content: [{ type: 'text', text: `Memory added successfully: ${memoryId}` }]
-        };
-      }
-
-      case 'search_memory': {
-        const response = await axios.post(`${PERSISTQ_URL}/api/memory/search`, {
-          query: args.query,
-          limit: args.limit || 10,
-          threshold: 0.7
-        }, {
-          headers: {
-            'Authorization': `Bearer ${API_KEY}`,
-            'Content-Type': 'application/json'
-          }
-        });
-        const results = response.data.data || response.data.memories || [];
-        const text = results.length > 0
-          ? results.map(r => `[${r.id}] ${(r.text || r.content || '').substring(0, 200)}... (Score: ${r.score?.toFixed(2) || 'N/A'})`).join('\n\n')
-          : 'No memories found';
-        return {
-          content: [{ type: 'text', text }]
-        };
-      }
-
-      case 'get_memory_stats': {
-        const response = await axios.get(`${PERSISTQ_URL}/api/memory/stats`, {
-          headers: {
-            'Authorization': `Bearer ${API_KEY}`
-          }
-        });
-        const stats = response.data.data || response.data.stats || response.data || {};
-        return {
-          content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }]
-        };
-      }
-
-      case 'list_memories': {
-        const params = new URLSearchParams();
-        if (args.project) params.append('project', args.project);
-        if (args.limit) params.append('limit', String(args.limit));
-        if (args.offset) params.append('offset', String(args.offset));
-
-        const response = await axios.get(`${PERSISTQ_URL}/api/memory/list?${params.toString()}`, {
-          headers: {
-            'Authorization': `Bearer ${API_KEY}`
-          }
-        });
-        const memories = response.data.data?.memories || response.data.memories || [];
-        const text = memories.length > 0
-          ? memories.map(m => `[${m.id}]\nProject: ${m.project}\nContent: ${m.content}\nCreated: ${m.createdAt}\n`).join('\n')
-          : 'No memories found';
-        return {
-          content: [{ type: 'text', text }]
-        };
-      }
-
-      default:
-        throw new Error(`Unknown tool: ${name}`);
-    }
-  } catch (error) {
-    return {
-      content: [{ type: 'text', text: `Error: ${error.message}` }],
-      isError: true
-    };
-  }
-});
-
-// Resources: list_resources
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-  resources: [
-    {
-      uri: 'persistq://memories/all',
-      name: 'All Memories',
-      description: 'List of all stored memories',
-      mimeType: 'application/json'
-    },
-    {
-      uri: 'persistq://stats',
-      name: 'Memory Statistics',
-      description: 'Overview of memory storage',
-      mimeType: 'application/json'
-    }
-  ]
-}));
-
-// Resources: read_resource
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  const { uri } = request.params;
-
-  try {
-    if (uri === 'persistq://memories/all') {
-      const response = await axios.get(`${PERSISTQ_URL}/api/memory/list?limit=100&offset=0`, {
-        headers: {
-          'Authorization': `Bearer ${API_KEY}`
-        }
-      });
-      return {
-        contents: [{
-          uri,
-          mimeType: 'application/json',
-          text: JSON.stringify(response.data.memories || [], null, 2)
-        }]
-      };
-    }
-
-    if (uri === 'persistq://stats') {
-      const response = await axios.get(`${PERSISTQ_URL}/api/memory/stats`, {
-        headers: {
-          'Authorization': `Bearer ${API_KEY}`
-        }
-      });
-      const stats = response.data.stats || response.data || {};
-      return {
-        contents: [{
-          uri,
-          mimeType: 'application/json',
-          text: JSON.stringify(stats, null, 2)
-        }]
-      };
-    }
-
-    throw new Error(`Unknown resource: ${uri}`);
-  } catch (error) {
-    throw new Error(`Failed to read resource: ${error.message}`);
-  }
-});
-
-// Start server with stdio transport
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error('[PersistQ MCP Server] Started on stdio');
-}
-
-main().catch((error) => {
-  console.error('[PersistQ MCP Server] Fatal error:', error);
-  process.exit(1);
-});
+#!/usr/bin/env node
+/**
+ * PersistQ MCP Server (Stdio Transport)
+ * Uses official @modelcontextprotocol/sdk for stdio communication with Claude Code
+ * Connects to PersistQ HTTP server on port 3000
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} = require('@modelcontextprotocol/sdk/types.js');
+const axios = require('axios');
+
+const PERSISTQ_URL = process.env.PERSISTQ_URL || 'http://localhost:3000';
+const API_KEY = process.env.PERSISTQ_API_KEY || 'pq_9df422f134ef9ec93e8337dd5bde0540dfd3d0de714e6e00379f3f7f174cfdff';
+const TOPIC = process.env.PERSISTQ_TOPIC || 'ClaudeConversations';
+
+// Global error handlers - all logs MUST go to stderr to keep stdout clean
+process.on('uncaughtException', (error) => {
+  console.error('[PersistQ MCP Server] FATAL: Uncaught exception:', error.message);
+  console.error(error.stack);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('[PersistQ MCP Server] FATAL: Unhandled promise rejection:', reason);
+  process.exit(1);
+});
+
+// Log configuration on startup (stderr only)
+console.error('[PersistQ MCP Server] Configuration:');
+console.error(`  PERSISTQ_URL: ${PERSISTQ_URL}`);
+console.error(`  PERSISTQ_TOPIC: ${TOPIC}`);
+console.error(`  API Key: ${API_KEY ? '[SET]' : '[NOT SET]'}`);
+
+// Create MCP server
+const server = new Server(
+  {
+    name: 'persistq-mcp-server',
+    version: '1.0.0'
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {}
+      // Note: GitHub Copilot CLI only supports tools (not resources)
+      // Resources remain available for Claude Code compatibility
+    }
+  }
+);
+
+// Tool: list_tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'add_memory',
+      description: 'Add a new memory to PersistQ',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'The memory content to store' },
+          topic: { type: 'string', description: 'Category or topic for this memory', default: TOPIC },
+          metadata: { type: 'object', description: 'Additional metadata' }
+        },
+        required: ['text']
+      }
+    },
+    {
+      name: 'search_memory',
+      description: 'Search memories by keyword or topic',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Search query or keyword' },
+          topic: { type: 'string', description: 'Filter by topic' },
+          limit: { type: 'number', description: 'Maximum results', default: 10 }
+        },
+        required: ['query']
+      }
+    },
+    {
+      name: 'get_memory_stats',
+      description: 'Get statistics about stored memories',
+      inputSchema: {
+        type: 'object',
+        properties: {}
+      }
+    },
+    {
+      name: 'list_memories',
+      description: 'List memories with optional filtering by project/tag',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          project: { type: 'string', description: 'Filter by project/tag name' },
+          limit: { type: 'number', description: 'Maximum results', default: 10 },
+          offset: { type: 'number', description: 'Offset for pagination', default: 0 }
+        }
+      }
+    }
+  ]
+}));
+
+// Tool: call_tool
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'add_memory': {
+        const response = await axios.post(`${PERSISTQ_URL}/api/memory`, {
+          content: args.text,
+          project: args.topic || TOPIC,
+          metadata: args.metadata || {}
+        }, {
+          headers: {
+            'Authorization': `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json'
+          }
+        });
+        const memoryId = response.data.data?.memoryId || response.data.memory?.id || response.data.id || 'OK';
+        return {
+          content: [{ type: 'text', text: `Memory added successfully: ${memoryId}` }]
+        };
+      }
+
+      case 'search_memory': {
+        const response = await axios.post(`${PERSISTQ_URL}/api/memory/search`, {
+          query: args.query,
+          limit: args.limit || 10,
+          threshold: 0.7
+        }, {
+          headers: {
+            'Authorization': `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json'
+          }
+        });
+        const results = response.data.data || response.data.memories || [];
+        const text = results.length > 0
+          ? results.map(r => `[${r.id}] ${(r.text || r.content || '').substring(0, 200)}... (Score: ${r.score?.toFixed(2) || 'N/A'})`).join('\n\n')
+          : 'No memories found';
+        return {
+          content: [{ type: 'text', text }]
+        };
+      }
+
+      case 'get_memory_stats': {
+        const response = await axios.get(`${PERSISTQ_URL}/api/memory/stats`, {
+          headers: {
+            'Authorization': `Bearer ${API_KEY}`
+          }
+        });
+        const stats = response.data.data || response.data.stats || response.data || {};
+        return {
+          content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }]
+        };
+      }
+
+      case 'list_memories': {
+        const params = new URLSearchParams();
+        if (args.project) params.append('project', args.project);
+        if (args.limit) params.append('limit', String(args.limit));
+        if (args.offset) params.append('offset', String(args.offset));
+
+        const response = await axios.get(`${PERSISTQ_URL}/api/memory/list?${params.toString()}`, {
+          headers: {
+            'Authorization': `Bearer ${API_KEY}`
+          }
+        });
+        const memories = response.data.data?.memories || response.data.memories || [];
+        const text = memories.length > 0
+          ? memories.map(m => `[${m.id}]\nProject: ${m.project}\nContent: ${m.content}\nCreated: ${m.createdAt}\n`).join('\n')
+          : 'No memories found';
+        return {
+          content: [{ type: 'text', text }]
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    // Log error to stderr for debugging (never stdout)
+    console.error(`[PersistQ MCP Server] Tool '${name}' error:`, error.message);
+    if (error.response) {
+      console.error(`  HTTP Status: ${error.response.status}`);
+      console.error(`  Response Data:`, JSON.stringify(error.response.data));
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Error executing ${name}: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+});
+
+// Resources: list_resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: 'persistq://memories/all',
+      name: 'All Memories',
+      description: 'List of all stored memories',
+      mimeType: 'application/json'
+    },
+    {
+      uri: 'persistq://stats',
+      name: 'Memory Statistics',
+      description: 'Overview of memory storage',
+      mimeType: 'application/json'
+    }
+  ]
+}));
+
+// Resources: read_resource
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  try {
+    if (uri === 'persistq://memories/all') {
+      const response = await axios.get(`${PERSISTQ_URL}/api/memory/list?limit=100&offset=0`, {
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`
+        }
+      });
+      return {
+        contents: [{
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(response.data.memories || [], null, 2)
+        }]
+      };
+    }
+
+    if (uri === 'persistq://stats') {
+      const response = await axios.get(`${PERSISTQ_URL}/api/memory/stats`, {
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`
+        }
+      });
+      const stats = response.data.stats || response.data || {};
+      return {
+        contents: [{
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(stats, null, 2)
+        }]
+      };
+    }
+
+    throw new Error(`Unknown resource: ${uri}`);
+  } catch (error) {
+    console.error(`[PersistQ MCP Server] Resource read error for '${uri}':`, error.message);
+    throw new Error(`Failed to read resource '${uri}': ${error.message}`);
+  }
+});
+
+// Start server with stdio transport
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[PersistQ MCP Server] Started on stdio');
+  console.error('[PersistQ MCP Server] Protocol versions supported: 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07');
+  console.error('[PersistQ MCP Server] Ready to receive requests');
+}
+
+main().catch((error) => {
+  console.error('[PersistQ MCP Server] Fatal startup error:', error.message);
+  console.error('Stack trace:', error.stack);
+  process.exit(1);
+});