rag-memory-pg-mcp 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,12 +5,47 @@ 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).
 
+## [2.2.0] - 2026-01-05
+
+### Breaking Changes 🔴
+- **Renamed `readGraph` → `getGraph`** due to Cursor API conflict
+- The `readGraph` name was causing the tool to be ignored/blocked by Cursor
+- Handler supports both names for backward compatibility
+
+### Fixed 🐛
+- **Tool loading in CLIENT mode** - now correctly shows 10 tools (was showing 9)
+- Root cause: `readGraph` conflicted with Cursor internal API
+- Solution: Renamed to `getGraph` - all tools now load properly
+
+### Technical Details
+- Debug analysis showed server was sending 10 tools correctly
+- Cursor was blocking/ignoring the `readGraph` tool during registration
+- Tool name conflict resolved by renaming
+
+## [2.1.1] - 2026-01-05
+
+### Added ✨
+- **Server instructions** for AI models with key principles and workflows
+- **Pre-defined prompts** (store-knowledge, search-knowledge, explore-graph)
+- **Enhanced tool descriptions** following MCP best practices
+- Prominent **English language requirement** warnings throughout
+
+### Changed
+- All tool descriptions now include examples and use cases
+- Parameter descriptions are more detailed and actionable
+- Better guidance for AI models on tool selection
+
+### Documentation
+- Added language requirement warnings in README
+- Server metadata includes comprehensive instructions
+- Prompts provide guided workflows for common tasks
+
 ## [2.1.0] - 2026-01-05
 
 ### Added ✨
 - **TOOLS_MODE environment variable** for flexible tool sets
-- `TOOLS_MODE=client` - 11 essential tools for daily memory operations (recommended)
-- `TOOLS_MODE=maintenance` - 10 admin/cleanup tools for database management
+- `TOOLS_MODE=client` - 10 essential tools for daily memory operations (recommended)
+- `TOOLS_MODE=maintenance` - 11 admin/cleanup tools for database management
 - `TOOLS_MODE=full` - All 21 tools (default)
 - Automatic updates via `@latest` in all npx commands
 - UPDATE_GUIDE.md with update instructions

package/README.md

@@ -154,6 +154,8 @@ Then restart Windsurf.
 - **Hybrid Search**: Combines text and semantic search
 - **Multi-Machine Sync**: PostgreSQL backend enables real-time sync across devices
 
+> **⚠️ Important:** All content (entities, documents, queries) should be stored and searched in **English** for optimal embedding and search performance. The embedding models are trained on English text and work best with English input.
+
 ## 📦 Installation Options
 
 ### Option 1: Direct via npx (Recommended)
@@ -184,19 +186,19 @@ npm install -g github:kshidenko/rag-memory-pg-mcp
 ### Tools Mode
 
 - **`full`** (default) - All 21 tools for complete functionality
-- **`client`** - 11 essential tools for daily memory operations (recommended for most users)
-- **`maintenance`** - 10 admin/cleanup tools for database management
+- **`client`** - 10 essential tools for daily memory operations (recommended for most users)
+- **`maintenance`** - 11 admin/cleanup tools for database management
 
 <details>
 <summary><b>Tools by Mode</b></summary>
 
-**CLIENT mode (11 tools) - Recommended for daily use:**
+**CLIENT mode (10 tools) - Recommended for daily use:**
 - Knowledge Graph: createEntities, createRelations, addObservations, searchNodes, openNodes
 - Documents: processDocument (⭐ main tool)
 - Search: hybridSearch, getDetailedContext
-- Info: readGraph, getKnowledgeGraphStats
+- Info: getGraph, getKnowledgeGraphStats
 
-**MAINTENANCE mode (10 tools) - For cleanup and admin:**
+**MAINTENANCE mode (11 tools) - For cleanup and admin:**
 - Cleanup: deleteEntities, deleteRelations, deleteObservations, deleteDocuments
 - Advanced: storeDocument, chunkDocument, embedChunks, embedAllEntities
 - Utilities: listDocuments, extractTerms, linkEntitiesToDocument
@@ -208,6 +210,8 @@ npm install -g github:kshidenko/rag-memory-pg-mcp
 
 ## Available Tools (21 total)
 
+> **Language Note:** All tools expect English input for entity names, observations, document content, and search queries. This ensures optimal embedding quality and search accuracy.
+
 ### Document Processing
 
 #### `processDocument` ⭐ Recommended

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-memory-pg-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "PostgreSQL-based RAG Memory MCP Server with Supabase - knowledge graph + semantic search",
   "type": "module",
   "main": "src/index.js",

package/src/handlers.js

@@ -102,7 +102,8 @@ async function executeToolMethod(name, args, manager) {
         includeEntities: args.includeEntities,
       });
 
-    case 'readGraph':
+    case 'getGraph':
+    case 'readGraph': // Backward compatibility
       return manager.readGraph();
 
     // ==================== UTILITIES ====================

package/src/index.js

@@ -20,11 +20,14 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
 import { RAGKnowledgeGraphManager } from './manager.js';
 import { getToolDefinitions } from './tools.js';
 import { filterToolsByMode } from './tool-modes.js';
+import { getPromptDefinitions } from './prompts.js';
 import { handleToolCall, createErrorResponse } from './handlers.js';
 
 // ==================== CONFIGURATION ====================
@@ -41,8 +44,8 @@ if (!SUPABASE_URL || !SUPABASE_KEY) {
 
 // Log active tools mode
 const modeDescriptions = {
-  client: 'CLIENT mode (11 essential tools for daily use)',
-  maintenance: 'MAINTENANCE mode (10 admin/cleanup tools)',
+  client: 'CLIENT mode (10 essential tools for daily use)',
+  maintenance: 'MAINTENANCE mode (11 admin/cleanup tools)',
   full: 'FULL mode (all 21 tools)'
 };
 console.error(`🔧 Tools: ${modeDescriptions[TOOLS_MODE] || 'FULL mode (default)'}`);
@@ -59,11 +62,36 @@ console.error(`📊 Active tools: ${activeTools.length}/${allTools.length}`);
 const server = new Server(
   {
     name: 'rag-memory-pg',
-    version: '2.0.0',
+    version: '2.2.0',
+    description: 'RAG-enabled memory with PostgreSQL/Supabase backend. Provides knowledge graph, document management, and semantic search. All content should be in English for optimal performance.',
+    instructions: `This is a RAG (Retrieval-Augmented Generation) memory system with knowledge graph capabilities.
+
+KEY PRINCIPLES:
+1. ALL content (entities, documents, queries) must be in ENGLISH for optimal embedding and search
+2. Use processDocument for storing documentation/code examples
+3. Use createEntities + createRelations for structured knowledge
+4. Use hybridSearch or getDetailedContext for finding information
+
+RECOMMENDED WORKFLOW:
+- Store knowledge: processDocument (documents) + createEntities (concepts) + createRelations (links)
+- Search knowledge: hybridSearch (documents) or searchNodes (entities)
+- Explore: readGraph (full overview) or getKnowledgeGraphStats (statistics)
+
+TOOL MODES:
+- client: 10 essential tools for daily use (recommended)
+- maintenance: 11 admin/cleanup tools
+- full: all 21 tools (default)
+
+EMBEDDING MODES:
+- local: Free, private, slower (default)
+- openai: 10-100x faster, cloud-based (recommended)
+
+Use English for all operations to ensure accurate semantic search and embedding quality.`,
   },
   {
     capabilities: {
       tools: {},
+      prompts: {},
     },
   }
 );
@@ -79,6 +107,46 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools: activeTools };
 });
 
+/**
+ * List available prompts
+ */
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return { prompts: getPromptDefinitions() };
+});
+
+/**
+ * Get specific prompt
+ */
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const prompts = getPromptDefinitions();
+  const prompt = prompts.find(p => p.name === request.params.name);
+  
+  if (!prompt) {
+    throw new Error(`Prompt not found: ${request.params.name}`);
+  }
+  
+  // Replace template variables
+  let messages = [{
+    role: 'user',
+    content: {
+      type: 'text',
+      text: prompt.prompt,
+    },
+  }];
+  
+  // Replace {{variable}} in prompt with actual arguments
+  if (request.params.arguments) {
+    Object.entries(request.params.arguments).forEach(([key, value]) => {
+      messages[0].content.text = messages[0].content.text.replace(
+        new RegExp(`{{${key}}}`, 'g'),
+        value
+      );
+    });
+  }
+  
+  return { messages };
+});
+
 /**
  * Handle tool calls
  */

package/src/prompts.js

@@ -0,0 +1,78 @@
+/**
+ * MCP Prompts
+ * 
+ * Pre-defined prompts that help users and AI models understand how to use the RAG Memory system effectively.
+ * 
+ * @module prompts
+ */
+
+export function getPromptDefinitions() {
+  return [
+    {
+      name: 'store-knowledge',
+      description: 'Store new knowledge (documentation, code examples, or concepts) in RAG memory',
+      arguments: [
+        {
+          name: 'topic',
+          description: 'Topic or subject of the knowledge (e.g., "Next.js routing", "PostgreSQL optimization")',
+          required: true,
+        },
+        {
+          name: 'content',
+          description: 'The actual content/documentation to store',
+          required: true,
+        },
+      ],
+      prompt: `I'll help you store knowledge about {{topic}} in the RAG memory system.
+
+**Best Practices:**
+1. All content must be in English for optimal search performance
+2. Use clear, descriptive entity names
+3. Add comprehensive observations with specific details
+4. Create relationships between related concepts
+
+**Steps:**
+1. Create entities for main concepts
+2. Add detailed observations
+3. Create relationships to connect knowledge
+4. Store full documentation using processDocument
+
+Let me process "{{content}}" and create a comprehensive knowledge graph entry.`,
+    },
+    {
+      name: 'search-knowledge',
+      description: 'Search for information in the RAG memory using hybrid semantic search',
+      arguments: [
+        {
+          name: 'query',
+          description: 'What are you looking for? (in English)',
+          required: true,
+        },
+      ],
+      prompt: `I'll search the RAG memory for information about "{{query}}".
+
+**Search Strategy:**
+1. Using hybridSearch for semantic + text matching
+2. Query in English for best embedding results
+3. Retrieving top relevant document chunks
+4. Including related entities from knowledge graph
+
+Searching now...`,
+    },
+    {
+      name: 'explore-graph',
+      description: 'Explore the knowledge graph to see what information is stored',
+      arguments: [],
+      prompt: `I'll show you the complete knowledge graph structure.
+
+**What you'll see:**
+- All entities (people, projects, technologies, concepts)
+- Relationships between entities
+- Total counts and statistics
+
+This gives you a bird's-eye view of all stored knowledge.
+
+Reading graph now...`,
+    },
+  ];
+}

package/src/tool-modes.js

@@ -27,7 +27,7 @@ export const TOOL_MODES = {
     'getDetailedContext',  // Get rich context with entities
     
     // Utilities - Basic info
-    'readGraph',           // View knowledge graph
+    'getGraph',            // View knowledge graph (renamed from readGraph)
     'getKnowledgeGraphStats', // See statistics
   ],
 

package/src/tools.js

@@ -13,22 +13,33 @@
  * @returns {object[]} Array of tool definitions
  */
 export function getToolDefinitions() {
-  return [
+  const tools = [
     // ==================== ENTITY TOOLS ====================
     {
       name: 'createEntities',
-      description: 'Create new entities in the knowledge graph',
+      description: 'Create new entities in the knowledge graph. Use this to store structured information about people, projects, technologies, concepts, or any important items. Entity names and observations should be in English for consistency.',
       inputSchema: {
         type: 'object',
         properties: {
           entities: {
             type: 'array',
+            description: 'Array of entities to create',
             items: {
               type: 'object',
               properties: {
-                name: { type: 'string' },
-                entityType: { type: 'string' },
-                observations: { type: 'array', items: { type: 'string' } },
+                name: { 
+                  type: 'string',
+                  description: 'Unique entity name in English. Examples: "React", "John Doe", "NextJS Project"'
+                },
+                entityType: { 
+                  type: 'string',
+                  description: 'Entity category in English. Examples: "TECHNOLOGY", "PERSON", "PROJECT", "CONCEPT"'
+                },
+                observations: { 
+                  type: 'array', 
+                  items: { type: 'string' },
+                  description: 'Facts and observations about this entity in English. Examples: ["JavaScript library", "Created by Facebook", "Used for UI development"]'
+                },
               },
               required: ['name', 'entityType', 'observations'],
             },
@@ -39,18 +50,28 @@ export function getToolDefinitions() {
     },
     {
       name: 'createRelations',
-      description: 'Create relationships between entities',
+      description: 'Create relationships between existing entities in the knowledge graph. Use this to connect related concepts, show dependencies, or build knowledge networks. Relationship types should be in English.',
       inputSchema: {
         type: 'object',
         properties: {
           relations: {
             type: 'array',
+            description: 'Array of relationships to create between entities',
             items: {
               type: 'object',
               properties: {
-                from: { type: 'string' },
-                to: { type: 'string' },
-                relationType: { type: 'string' },
+                from: { 
+                  type: 'string',
+                  description: 'Source entity name (must exist). Example: "React"'
+                },
+                to: { 
+                  type: 'string',
+                  description: 'Target entity name (must exist). Example: "JavaScript"'
+                },
+                relationType: { 
+                  type: 'string',
+                  description: 'Relationship type in English. Examples: "BUILT_WITH", "USES", "DEPENDS_ON", "CREATED_BY", "PART_OF"'
+                },
               },
               required: ['from', 'to', 'relationType'],
             },
@@ -61,17 +82,25 @@ export function getToolDefinitions() {
     },
     {
       name: 'addObservations',
-      description: 'Add observations to existing entities',
+      description: 'Add new observations (facts, notes, details) to existing entities. Use this to enrich entities with additional information over time. All observations should be in English for consistency.',
       inputSchema: {
         type: 'object',
         properties: {
           observations: {
             type: 'array',
+            description: 'Array of observations to add to entities',
             items: {
               type: 'object',
               properties: {
-                entityName: { type: 'string' },
-                contents: { type: 'array', items: { type: 'string' } },
+                entityName: { 
+                  type: 'string',
+                  description: 'Name of existing entity. Example: "React"'
+                },
+                contents: { 
+                  type: 'array', 
+                  items: { type: 'string' },
+                  description: 'Array of new observations in English. Examples: ["Released version 18", "Added concurrent features", "Improved performance"]'
+                },
               },
               required: ['entityName', 'contents'],
             },
@@ -82,23 +111,34 @@ export function getToolDefinitions() {
     },
     {
       name: 'searchNodes',
-      description: 'Search for entities by name or type',
+      description: 'Search for entities in the knowledge graph by name or type. Use English keywords for best results. Returns matching entities with their types and observations.',
       inputSchema: {
         type: 'object',
         properties: {
-          query: { type: 'string' },
-          limit: { type: 'number', default: 10 },
+          query: { 
+            type: 'string',
+            description: 'Search query in English. Can search by entity name or type. Examples: "React", "PERSON", "database"'
+          },
+          limit: { 
+            type: 'number', 
+            default: 10,
+            description: 'Maximum number of entities to return (default: 10)'
+          },
         },
         required: ['query'],
       },
     },
     {
       name: 'openNodes',
-      description: 'Get specific entities by name',
+      description: 'Get complete details of specific entities by their exact names. Returns entity type, all observations, and related connections. Use this to retrieve full information about known entities.',
       inputSchema: {
         type: 'object',
         properties: {
-          names: { type: 'array', items: { type: 'string' } },
+          names: { 
+            type: 'array', 
+            items: { type: 'string' },
+            description: 'Array of exact entity names to retrieve. Examples: ["React", "Next.js", "TypeScript"]'
+          },
         },
         required: ['names'],
       },
@@ -165,15 +205,32 @@ export function getToolDefinitions() {
     // ==================== DOCUMENT TOOLS ====================
     {
       name: 'processDocument',
-      description: 'RECOMMENDED: Store document with full pipeline (store → chunk → embed)',
+      description: '⭐ RECOMMENDED: Store document with full pipeline (store → chunk → embed). Use this for adding any documentation, code examples, or knowledge. Content should be in English for optimal search performance. Automatically chunks text and generates embeddings.',
       inputSchema: {
         type: 'object',
         properties: {
-          id: { type: 'string', description: 'Unique document identifier' },
-          content: { type: 'string', description: 'Document content' },
-          maxChunkSize: { type: 'number', default: 500, description: 'Max chunk size' },
-          overlap: { type: 'number', default: 50, description: 'Chunk overlap' },
-          metadata: { type: 'object', description: 'Optional metadata' },
+          id: { 
+            type: 'string', 
+            description: 'Unique document identifier. Use descriptive names like "nextjs-routing-docs" or "postgres-optimization-guide"'
+          },
+          content: { 
+            type: 'string', 
+            description: 'Document content in English. Can be markdown, code examples, documentation, or any text knowledge'
+          },
+          maxChunkSize: { 
+            type: 'number', 
+            default: 500, 
+            description: 'Maximum characters per chunk (default: 500). Smaller chunks = more precise search'
+          },
+          overlap: { 
+            type: 'number', 
+            default: 50, 
+            description: 'Character overlap between chunks (default: 50). Ensures context continuity'
+          },
+          metadata: { 
+            type: 'object', 
+            description: 'Optional metadata like {type: "documentation", source: "official", version: "1.0"}'
+          },
         },
         required: ['id', 'content'],
       },
@@ -240,7 +297,7 @@ export function getToolDefinitions() {
     },
     {
       name: 'embedAllEntities',
-      description: 'Generate embeddings for all entities',
+      description: 'Generate embeddings for all entities in the knowledge graph. Use this to enable semantic search on entities or after adding many new entities. No parameters required.',
       inputSchema: {
         type: 'object',
         properties: {},
@@ -250,32 +307,50 @@ export function getToolDefinitions() {
     // ==================== SEARCH TOOLS ====================
     {
       name: 'hybridSearch',
-      description: 'Search documents using hybrid search',
+      description: 'Search documents using hybrid semantic + text search. Query must be in English for best results. Returns relevant document chunks with similarity scores.',
       inputSchema: {
         type: 'object',
         properties: {
-          query: { type: 'string' },
-          limit: { type: 'number', default: 5 },
+          query: { 
+            type: 'string',
+            description: 'Search query in English. Examples: "React hooks usage", "authentication patterns", "database optimization"'
+          },
+          limit: { 
+            type: 'number', 
+            default: 5,
+            description: 'Maximum number of results to return (default: 5)'
+          },
         },
         required: ['query'],
       },
     },
     {
       name: 'getDetailedContext',
-      description: 'Get detailed context (semantic + graph search)',
+      description: 'Get detailed context combining semantic document search with related entities from knowledge graph. Query must be in English. Returns document chunks + connected entities for comprehensive understanding.',
       inputSchema: {
         type: 'object',
         properties: {
-          query: { type: 'string', description: 'Search query' },
-          limit: { type: 'number', default: 5 },
-          includeEntities: { type: 'boolean', default: true },
+          query: { 
+            type: 'string', 
+            description: 'Search query in English. Examples: "Next.js routing", "PostgreSQL optimization", "React state management"'
+          },
+          limit: { 
+            type: 'number', 
+            default: 5,
+            description: 'Maximum number of document results (default: 5)'
+          },
+          includeEntities: { 
+            type: 'boolean', 
+            default: true,
+            description: 'Include related entities from knowledge graph (default: true)'
+          },
         },
         required: ['query'],
       },
     },
     {
-      name: 'readGraph',
-      description: 'Read the entire knowledge graph',
+      name: 'getGraph',
+      description: 'Get the entire knowledge graph with all entities, relationships, and observations. Use this to retrieve complete overview of stored knowledge. Returns full graph structure for analysis or visualization. No parameters required.',
       inputSchema: {
         type: 'object',
         properties: {},
@@ -285,7 +360,7 @@ export function getToolDefinitions() {
     // ==================== UTILITY TOOLS ====================
     {
       name: 'getKnowledgeGraphStats',
-      description: 'Get statistics about the knowledge graph',
+      description: 'Get statistics about the knowledge graph including total counts of entities, relationships, documents, and chunks. Use this to understand the size and scope of stored knowledge. Returns entity_count, relationship_count, document_count, chunk_count, and type distributions. No parameters required.',
       inputSchema: {
         type: 'object',
         properties: {},
@@ -317,4 +392,6 @@ export function getToolDefinitions() {
       },
     },
   ];
+  
+  return tools;
 }

package/test-openai-embeddings.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-/**
- * Test script to verify OpenAI embeddings work correctly
- * 
- * Usage:
- *   MODE=openai OPENAI_API_KEY=sk-... node test-openai-embeddings.js
- * 
- * Or test local mode:
- *   MODE=local node test-openai-embeddings.js
- */
-
-import { RAGKnowledgeGraphManager } from './src/manager.js';
-
-async function testOpenAIEmbeddings() {
-  console.log('🧪 Testing OpenAI Embeddings Integration...\n');
-  
-  // Check env vars
-  const mode = (process.env.MODE || 'local').toLowerCase();
-  const hasOpenAIKey = !!process.env.OPENAI_API_KEY;
-  
-  console.log(`📋 Configuration:`);
-  console.log(`   MODE: ${mode}`);
-  console.log(`   OPENAI_API_KEY: ${hasOpenAIKey ? '✅ Set' : '❌ Not set'}`);
-  console.log();
-  
-  // Initialize manager
-  const manager = new RAGKnowledgeGraphManager(
-    process.env.SUPABASE_URL,
-    process.env.SUPABASE_SERVICE_KEY
-  );
-  
-  await manager.initialize();
-  
-  // Test embedding generation
-  console.log('🔮 Generating test embedding...');
-  const testText = 'This is a test for OpenAI embeddings with 384 dimensions';
-  
-  const startTime = Date.now();
-  const embedding = await manager.generateEmbedding(testText);
-  const duration = Date.now() - startTime;
-  
-  if (!embedding) {
-    console.error('❌ Failed to generate embedding');
-    process.exit(1);
-  }
-  
-  console.log(`✅ Embedding generated in ${duration}ms`);
-  console.log(`   Dimensions: ${embedding.length}`);
-  console.log(`   First 5 values: [${embedding.slice(0, 5).map(v => v.toFixed(4)).join(', ')}...]`);
-  console.log(`   Mode used: ${manager.mode}`);
-  
-  // Verify dimensions
-  if (embedding.length !== 384) {
-    console.error(`❌ Expected 384 dimensions, got ${embedding.length}`);
-    process.exit(1);
-  }
-  
-  // Test multiple embeddings for performance
-  console.log('\n⚡ Performance test (5 embeddings)...');
-  const perfStart = Date.now();
-  
-  for (let i = 0; i < 5; i++) {
-    await manager.generateEmbedding(`Test text ${i}`);
-  }
-  
-  const avgTime = (Date.now() - perfStart) / 5;
-  console.log(`   Average time: ${avgTime.toFixed(0)}ms per embedding`);
-  
-  if (mode === 'openai') {
-    console.log(`   Expected: 50-200ms (OpenAI is fast!)`);
-  } else {
-    console.log(`   Expected: 200-2000ms (Local model)`);
-  }
-  
-  console.log('\n✅ All tests passed!');
-}
-
-testOpenAIEmbeddings().catch(error => {
-  console.error('❌ Test failed:', error.message);
-  process.exit(1);
-});