@pragmatic-growth/memory-mcp 1.0.0 → 2.1.0

package/dist/index.js

@@ -71,11 +71,11 @@ async function callRemoteServer(method, params) {
  */
 async function initializeRemoteSession() {
     await callRemoteServer('initialize', {
-        protocolVersion: '2024-11-05',
+        protocolVersion: '2025-11-25',
         capabilities: {},
         clientInfo: {
             name: 'pg-memory-stdio',
-            version: '1.0.0',
+            version: '2.1.0',
         },
     });
 }
@@ -95,81 +95,163 @@ async function main() {
     // Create local MCP server
     const server = new McpServer({
         name: 'pg-memory',
-        version: '1.0.0',
+        version: '2.1.0',
         description: `PG-Memory knowledge base (${modeLabel} mode)`,
     });
-    // Register tools that proxy to remote server
-    // These match the tools registered on the remote server
-    server.tool('search_tax_knowledge', 'Search the US non-resident tax compliance knowledge base using semantic similarity', {
-        query: z.string().describe('The tax question or topic to search for'),
+    // ============================================================
+    // READ-ONLY TOOLS (available in all modes)
+    // ============================================================
+    // Tool 1: Search Knowledge (matches HTTP server's search_knowledge)
+    server.tool('search_knowledge', `Search the nonresident.tax knowledge base using semantic similarity.
+
+This knowledge base contains comprehensive information about:
+- Services: LLC formation, tax filing, registered agent, accounting
+- Pricing: Package costs, annual fees, consultation fees
+- Tax compliance: Form 5472, Form 1120, ECI rules, penalties, deadlines
+- Company formation: Wyoming LLC, Delaware LLC, single-member LLC
+- Banking: Mercury, Wise, US bank account requirements
+- Process: Onboarding steps, document requirements, timelines
+- Dissolution: LLC closure, final filings, IRS compliance
+
+Returns relevant articles with relevance scores. Use get_article to retrieve full content.`, {
+        query: z.string().describe('The question or topic to search for'),
         limit: z.number().optional().describe('Maximum number of results to return (default: 5)'),
         threshold: z.number().optional().describe('Minimum similarity threshold 0-1 (default: 0.55)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'search_tax_knowledge',
+            name: 'search_knowledge',
             arguments: args,
         });
         return result;
     });
-    server.tool('answer_question', 'Answer a tax question using the knowledge base with RAG', {
-        question: z.string().describe('The tax question to answer'),
-        context: z.string().optional().describe('Additional context'),
+    // Tool 2: Get Article
+    server.tool('get_article', `Retrieve the complete content of a knowledge base article by ID.
+
+Use this tool when:
+- You have an article ID from search_knowledge or list_articles
+- You need the full article content (not just summary)
+- You want to verify specific details from search results
+
+Returns: Full article with title, content, summary, category, tags, version, and last update date.`, {
+        article_id: z.string().describe('The article ID (e.g., art_abc123)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'answer_question',
+            name: 'get_article',
             arguments: args,
         });
         return result;
     });
-    server.tool('get_article', 'Retrieve the complete content of a knowledge base article by its ID', {
-        article_id: z.string().describe('The article ID (e.g., art_abc123)'),
+    // Tool 3: Answer Question (Full RAG)
+    server.tool('answer_question', `Answer a customer question using the knowledge base with full RAG.
+
+This tool:
+1. Searches for relevant articles in the knowledge base
+2. If found: Generates an answer synthesizing the retrieved content
+3. If not found: Optionally generates a new article to fill the gap
+
+Use for questions about:
+- Services and pricing
+- Tax filing requirements and deadlines
+- LLC formation process
+- Bank account options
+- Document requirements
+- How onboarding works
+- Any nonresident.tax topic
+
+The answer includes source references for transparency.`, {
+        question: z.string().describe('The customer question to answer'),
+        context: z.string().optional().describe('Additional context about the question'),
+        generate_if_not_found: z.boolean().optional().describe('Generate new article if no relevant content found (default: true)'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'get_article',
+            name: 'answer_question',
             arguments: args,
         });
         return result;
     });
-    server.tool('list_articles', 'List recent articles from the knowledge base', {
-        limit: z.number().optional().describe('Maximum articles (default: 10)'),
-        category: z.string().optional().describe('Filter by category'),
+    // Tool 4: Log Unanswered
+    server.tool('log_unanswered', `Flag a customer question as unanswered for knowledge gap analysis.
+
+WHEN TO USE:
+- After search_knowledge returns no relevant results
+- When existing articles don't fully answer the question
+- When a customer asks something completely new
+- To track recurring questions that need dedicated articles
+
+WHY IT MATTERS:
+- Flagged questions appear in the admin "Knowledge Gaps" section
+- Helps prioritize which new articles to create
+- Builds a list of topics customers actually need
+- Improves the knowledge base over time`, {
+        query: z.string().describe('The question that could not be answered'),
+        reason: z.string().optional().describe('Reason why the question could not be answered'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'list_articles',
+            name: 'log_unanswered',
             arguments: args,
         });
         return result;
     });
-    server.tool('log_unanswered', 'Explicitly flag a question as unanswered for gap analysis', {
-        query: z.string().describe('The question that could not be answered'),
-        reason: z.string().optional().describe('Reason why the question could not be answered'),
+    // Tool 5: List Articles
+    server.tool('list_articles', `Browse articles in the knowledge base with optional filtering.
+
+Parameters:
+- limit: Number of articles (default 10, max 50)
+- category: Filter by category slug (use list_categories first)
+
+Returns article ID, title, and summary for each match.
+Use get_article with the ID to retrieve full content.
+
+WORKFLOW:
+1. Call list_categories to discover available categories
+2. Call list_articles with specific category for focused results
+3. Call get_article for articles that look relevant`, {
+        limit: z.number().optional().describe('Number of articles to return (max 50)'),
+        category: z.string().optional().describe('Filter by category slug'),
     }, async (args) => {
         const result = await callRemoteServer('tools/call', {
-            name: 'log_unanswered',
+            name: 'list_articles',
             arguments: args,
         });
         return result;
     });
-    server.tool('health_check', 'Check the health status of the knowledge base system', {}, async () => {
+    // Tool 6: Health Check
+    server.tool('health_check', 'Check the health status of the memory system.', {}, async () => {
         const result = await callRemoteServer('tools/call', {
             name: 'health_check',
             arguments: {},
         });
         return result;
     });
-    // Tool 7: List Categories (available in all modes)
-    server.tool('list_categories', 'List all categories in the knowledge base with article counts', {}, async () => {
+    // Tool 7: List Categories
+    server.tool('list_categories', `List all categories in the knowledge base with article counts.
+
+CRITICAL FOR EFFICIENT SEARCH:
+Categories help you quickly narrow down to relevant content.
+
+Returns for each category:
+- slug: Category identifier for filtering
+- name: Human-readable name
+- count: Number of articles
+- description: What the category covers
+
+RECOMMENDED WORKFLOW:
+1. Call list_categories to see what's available
+2. Call list_articles with category slug
+3. Call get_article for full content
+4. Or use search_knowledge for semantic search across all`, {}, async () => {
         const result = await callRemoteServer('tools/call', {
             name: 'list_categories',
             arguments: {},
         });
         return result;
     });
-    // === FULL MODE TOOLS ===
-    // These tools are only available when --full flag is passed or MCP_MODE=full
+    // ============================================================
+    // FULL MODE TOOLS (only available with --full flag or MCP_MODE=full)
+    // ============================================================
     if (isFullMode) {
         // Tool 8: Add Article
-        server.tool('add_article', 'Create a new article in the knowledge base (full mode only)', {
+        server.tool('add_article', 'Create a new article in the knowledge base. Automatically generates embedding for semantic search.', {
             title: z.string().describe('Article title'),
             content: z.string().describe('Article content in markdown format'),
             summary: z.string().optional().describe('Brief summary (auto-generated if not provided)'),
@@ -184,7 +266,7 @@ async function main() {
             return result;
         });
         // Tool 9: Edit Article
-        server.tool('edit_article', 'Update an existing article in the knowledge base (full mode only)', {
+        server.tool('edit_article', 'Update an existing article. Re-generates embedding if content changes.', {
             article_id: z.string().describe('Article ID to update'),
             title: z.string().optional().describe('New title'),
             content: z.string().optional().describe('New content'),
@@ -199,7 +281,7 @@ async function main() {
             return result;
         });
         // Tool 10: Remove Article
-        server.tool('remove_article', 'Soft-delete an article from the knowledge base (full mode only)', {
+        server.tool('remove_article', 'Soft-delete an article from the knowledge base. Article is marked as deleted but not permanently removed.', {
             article_id: z.string().describe('Article ID to remove'),
             reason: z.string().optional().describe('Reason for deletion (for audit log)'),
         }, async (args) => {
@@ -210,7 +292,7 @@ async function main() {
             return result;
         });
         // Tool 11: Rate Answer
-        server.tool('rate_answer', 'Rate a previous answer as helpful, unhelpful, or neutral (full mode only)', {
+        server.tool('rate_answer', 'Rate a previous answer as helpful, unhelpful, or neutral. Helps improve the knowledge base.', {
             query_id: z.string().describe('Query log ID from a previous answer_question response'),
             rating: z.number().describe('Rating: -1 (unhelpful), 0 (neutral), 1 (helpful)'),
             feedback: z.string().optional().describe('Optional text feedback'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pragmatic-growth/memory-mcp",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "MCP stdio client for PG-Memory knowledge base - connect AI agents to your PostgreSQL knowledge base via Model Context Protocol",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -93,11 +93,11 @@ async function callRemoteServer(method: string, params?: Record<string, unknown>
  */
 async function initializeRemoteSession(): Promise<void> {
   await callRemoteServer('initialize', {
-    protocolVersion: '2024-11-05',
+    protocolVersion: '2025-11-25',
     capabilities: {},
     clientInfo: {
       name: 'pg-memory-stdio',
-      version: '1.0.0',
+      version: '2.1.0',
     },
   });
 }
@@ -119,96 +119,162 @@ async function main(): Promise<void> {
   // Create local MCP server
   const server = new McpServer({
     name: 'pg-memory',
-    version: '1.0.0',
+    version: '2.1.0',
     description: `PG-Memory knowledge base (${modeLabel} mode)`,
   });
 
-  // Register tools that proxy to remote server
-  // These match the tools registered on the remote server
+  // ============================================================
+  // READ-ONLY TOOLS (available in all modes)
+  // ============================================================
 
+  // Tool 1: Search Knowledge (matches HTTP server's search_knowledge)
   server.tool(
-    'search_tax_knowledge',
-    'Search the US non-resident tax compliance knowledge base using semantic similarity',
+    'search_knowledge',
+    `Search the nonresident.tax knowledge base using semantic similarity.
+
+This knowledge base contains comprehensive information about:
+- Services: LLC formation, tax filing, registered agent, accounting
+- Pricing: Package costs, annual fees, consultation fees
+- Tax compliance: Form 5472, Form 1120, ECI rules, penalties, deadlines
+- Company formation: Wyoming LLC, Delaware LLC, single-member LLC
+- Banking: Mercury, Wise, US bank account requirements
+- Process: Onboarding steps, document requirements, timelines
+- Dissolution: LLC closure, final filings, IRS compliance
+
+Returns relevant articles with relevance scores. Use get_article to retrieve full content.`,
     {
-      query: z.string().describe('The tax question or topic to search for'),
+      query: z.string().describe('The question or topic to search for'),
       limit: z.number().optional().describe('Maximum number of results to return (default: 5)'),
       threshold: z.number().optional().describe('Minimum similarity threshold 0-1 (default: 0.55)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'search_tax_knowledge',
+        name: 'search_knowledge',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
     }
   );
 
+  // Tool 2: Get Article
   server.tool(
-    'answer_question',
-    'Answer a tax question using the knowledge base with RAG',
+    'get_article',
+    `Retrieve the complete content of a knowledge base article by ID.
+
+Use this tool when:
+- You have an article ID from search_knowledge or list_articles
+- You need the full article content (not just summary)
+- You want to verify specific details from search results
+
+Returns: Full article with title, content, summary, category, tags, version, and last update date.`,
     {
-      question: z.string().describe('The tax question to answer'),
-      context: z.string().optional().describe('Additional context'),
+      article_id: z.string().describe('The article ID (e.g., art_abc123)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'answer_question',
+        name: 'get_article',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
     }
   );
 
+  // Tool 3: Answer Question (Full RAG)
   server.tool(
-    'get_article',
-    'Retrieve the complete content of a knowledge base article by its ID',
+    'answer_question',
+    `Answer a customer question using the knowledge base with full RAG.
+
+This tool:
+1. Searches for relevant articles in the knowledge base
+2. If found: Generates an answer synthesizing the retrieved content
+3. If not found: Optionally generates a new article to fill the gap
+
+Use for questions about:
+- Services and pricing
+- Tax filing requirements and deadlines
+- LLC formation process
+- Bank account options
+- Document requirements
+- How onboarding works
+- Any nonresident.tax topic
+
+The answer includes source references for transparency.`,
     {
-      article_id: z.string().describe('The article ID (e.g., art_abc123)'),
+      question: z.string().describe('The customer question to answer'),
+      context: z.string().optional().describe('Additional context about the question'),
+      generate_if_not_found: z.boolean().optional().describe('Generate new article if no relevant content found (default: true)'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'get_article',
+        name: 'answer_question',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
     }
   );
 
+  // Tool 4: Log Unanswered
   server.tool(
-    'list_articles',
-    'List recent articles from the knowledge base',
+    'log_unanswered',
+    `Flag a customer question as unanswered for knowledge gap analysis.
+
+WHEN TO USE:
+- After search_knowledge returns no relevant results
+- When existing articles don't fully answer the question
+- When a customer asks something completely new
+- To track recurring questions that need dedicated articles
+
+WHY IT MATTERS:
+- Flagged questions appear in the admin "Knowledge Gaps" section
+- Helps prioritize which new articles to create
+- Builds a list of topics customers actually need
+- Improves the knowledge base over time`,
     {
-      limit: z.number().optional().describe('Maximum articles (default: 10)'),
-      category: z.string().optional().describe('Filter by category'),
+      query: z.string().describe('The question that could not be answered'),
+      reason: z.string().optional().describe('Reason why the question could not be answered'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'list_articles',
+        name: 'log_unanswered',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
     }
   );
 
+  // Tool 5: List Articles
   server.tool(
-    'log_unanswered',
-    'Explicitly flag a question as unanswered for gap analysis',
+    'list_articles',
+    `Browse articles in the knowledge base with optional filtering.
+
+Parameters:
+- limit: Number of articles (default 10, max 50)
+- category: Filter by category slug (use list_categories first)
+
+Returns article ID, title, and summary for each match.
+Use get_article with the ID to retrieve full content.
+
+WORKFLOW:
+1. Call list_categories to discover available categories
+2. Call list_articles with specific category for focused results
+3. Call get_article for articles that look relevant`,
     {
-      query: z.string().describe('The question that could not be answered'),
-      reason: z.string().optional().describe('Reason why the question could not be answered'),
+      limit: z.number().optional().describe('Number of articles to return (max 50)'),
+      category: z.string().optional().describe('Filter by category slug'),
     },
     async (args) => {
       const result = await callRemoteServer('tools/call', {
-        name: 'log_unanswered',
+        name: 'list_articles',
         arguments: args,
       }) as { content: Array<{ type: 'text'; text: string }> };
       return result;
     }
   );
 
+  // Tool 6: Health Check
   server.tool(
     'health_check',
-    'Check the health status of the knowledge base system',
+    'Check the health status of the memory system.',
     {},
     async () => {
       const result = await callRemoteServer('tools/call', {
@@ -219,10 +285,25 @@ async function main(): Promise<void> {
     }
   );
 
-  // Tool 7: List Categories (available in all modes)
+  // Tool 7: List Categories
   server.tool(
     'list_categories',
-    'List all categories in the knowledge base with article counts',
+    `List all categories in the knowledge base with article counts.
+
+CRITICAL FOR EFFICIENT SEARCH:
+Categories help you quickly narrow down to relevant content.
+
+Returns for each category:
+- slug: Category identifier for filtering
+- name: Human-readable name
+- count: Number of articles
+- description: What the category covers
+
+RECOMMENDED WORKFLOW:
+1. Call list_categories to see what's available
+2. Call list_articles with category slug
+3. Call get_article for full content
+4. Or use search_knowledge for semantic search across all`,
     {},
     async () => {
       const result = await callRemoteServer('tools/call', {
@@ -233,14 +314,15 @@ async function main(): Promise<void> {
     }
   );
 
-  // === FULL MODE TOOLS ===
-  // These tools are only available when --full flag is passed or MCP_MODE=full
+  // ============================================================
+  // FULL MODE TOOLS (only available with --full flag or MCP_MODE=full)
+  // ============================================================
 
   if (isFullMode) {
     // Tool 8: Add Article
     server.tool(
       'add_article',
-      'Create a new article in the knowledge base (full mode only)',
+      'Create a new article in the knowledge base. Automatically generates embedding for semantic search.',
       {
         title: z.string().describe('Article title'),
         content: z.string().describe('Article content in markdown format'),
@@ -261,7 +343,7 @@ async function main(): Promise<void> {
     // Tool 9: Edit Article
     server.tool(
       'edit_article',
-      'Update an existing article in the knowledge base (full mode only)',
+      'Update an existing article. Re-generates embedding if content changes.',
       {
         article_id: z.string().describe('Article ID to update'),
         title: z.string().optional().describe('New title'),
@@ -282,7 +364,7 @@ async function main(): Promise<void> {
     // Tool 10: Remove Article
     server.tool(
       'remove_article',
-      'Soft-delete an article from the knowledge base (full mode only)',
+      'Soft-delete an article from the knowledge base. Article is marked as deleted but not permanently removed.',
       {
         article_id: z.string().describe('Article ID to remove'),
         reason: z.string().optional().describe('Reason for deletion (for audit log)'),
@@ -299,7 +381,7 @@ async function main(): Promise<void> {
     // Tool 11: Rate Answer
     server.tool(
       'rate_answer',
-      'Rate a previous answer as helpful, unhelpful, or neutral (full mode only)',
+      'Rate a previous answer as helpful, unhelpful, or neutral. Helps improve the knowledge base.',
       {
         query_id: z.string().describe('Query log ID from a previous answer_question response'),
         rating: z.number().describe('Rating: -1 (unhelpful), 0 (neutral), 1 (helpful)'),