@prmichaelsen/remember-mcp 2.0.0 → 2.0.2

package/agent/scripts/uninstall.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# Agent Context Protocol (ACP) Uninstall Script
+# This script removes all ACP files from a project
+# Usage: ./agent/scripts/uninstall.sh [-y]
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Check for -y flag
+AUTO_CONFIRM=false
+if [ "$1" = "-y" ]; then
+    AUTO_CONFIRM=true
+fi
+
+echo -e "${YELLOW}Agent Context Protocol (ACP) Uninstall${NC}"
+echo "======================================"
+echo ""
+
+# Check if agent directory exists
+if [ ! -d "agent" ] && [ ! -f "AGENT.md" ]; then
+    echo -e "${YELLOW}No ACP files found in current directory${NC}"
+    exit 0
+fi
+
+# If not auto-confirmed, show instructions for agents
+if [ "$AUTO_CONFIRM" = false ]; then
+    echo -e "${BLUE}Note for AI Agents:${NC}"
+    echo "This script requires user confirmation to prevent accidental deletion."
+    echo "Please ask the user: 'Do you want to uninstall ACP from this project?'"
+    echo "If yes, rerun this script with: ./agent/scripts/uninstall.sh -y"
+    echo ""
+    echo -e "${RED}WARNING: This will permanently delete:${NC}"
+    echo "  - agent/ directory (all contents)"
+    echo "  - AGENT.md file"
+    echo ""
+    echo "Make sure you have committed any important changes to git."
+    echo ""
+    
+    read -p "Are you sure you want to remove all ACP files? (y/N) " -n 1 -r
+    echo
+    
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Uninstall cancelled. No files were deleted."
+        exit 0
+    fi
+fi
+
+echo ""
+echo "Removing ACP files..."
+
+# Remove agent directory
+if [ -d "agent" ]; then
+    rm -rf agent
+    echo -e "${GREEN}✓${NC} Removed agent/ directory"
+fi
+
+# Remove AGENT.md
+if [ -f "AGENT.md" ]; then
+    rm -f AGENT.md
+    echo -e "${GREEN}✓${NC} Removed AGENT.md"
+fi
+
+echo ""
+echo -e "${GREEN}Uninstall complete!${NC}"
+echo ""
+echo "All ACP files have been removed from this project."
+echo "Use 'git status' to see what was deleted."
+echo ""

package/agent/scripts/update.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# Agent Context Protocol (ACP) Update Script
+# This script updates AGENT.md, template files, and utility scripts from the repository
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Repository details
+REPO_URL="https://github.com/prmichaelsen/agent-context-protocol.git"
+BRANCH="mainline"
+
+echo -e "${BLUE}Agent Context Protocol (ACP) Updater${NC}"
+echo "======================================"
+echo ""
+
+# Check if AGENT.md exists
+if [ ! -f "AGENT.md" ]; then
+    echo -e "${RED}Error: AGENT.md not found in current directory${NC}"
+    echo "This script should be run from your project root where AGENT.md is located."
+    exit 1
+fi
+
+# Create temporary directory
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+echo "Fetching latest ACP files..."
+if ! git clone --depth 1 --branch "$BRANCH" "$REPO_URL" "$TEMP_DIR" &>/dev/null; then
+    echo -e "${RED}Error: Failed to fetch repository${NC}"
+    echo "Please check your internet connection and try again."
+    exit 1
+fi
+
+echo -e "${GREEN}✓${NC} Latest files fetched"
+echo ""
+
+echo "Updating ACP files..."
+
+# Update template files
+cp "$TEMP_DIR/agent/design/design.template.md" "agent/design/"
+cp "$TEMP_DIR/agent/design/requirements.template.md" "agent/design/"
+cp "$TEMP_DIR/agent/milestones/milestone-1-{title}.template.md" "agent/milestones/"
+cp "$TEMP_DIR/agent/tasks/task-1-{title}.template.md" "agent/tasks/"
+cp "$TEMP_DIR/agent/patterns/pattern.template.md" "agent/patterns/"
+cp "$TEMP_DIR/agent/patterns/bootstrap.template.md" "agent/patterns/"
+cp "$TEMP_DIR/agent/progress.template.yaml" "agent/"
+
+# Update AGENT.md
+cp "$TEMP_DIR/AGENT.md" "."
+
+# Update scripts
+cp "$TEMP_DIR/scripts/update.sh" "agent/scripts/"
+cp "$TEMP_DIR/scripts/check-for-updates.sh" "agent/scripts/"
+cp "$TEMP_DIR/scripts/uninstall.sh" "agent/scripts/"
+chmod +x agent/scripts/*.sh
+
+echo -e "${GREEN}✓${NC} All files updated"
+echo ""
+echo -e "${GREEN}Update complete!${NC}"
+echo ""
+echo -e "${BLUE}Next steps:${NC}"
+echo "1. Review changes: git diff"
+echo "2. See what changed: git status"
+echo "3. Revert if needed: git checkout <file>"
+echo ""
+echo "For detailed changelog:"
+echo "  https://github.com/prmichaelsen/agent-context-protocol/blob/mainline/CHANGELOG.md"
+echo ""

package/agent/tasks/task-1-{title}.template.md

@@ -0,0 +1,225 @@
+# Task {N}: {Descriptive Task Name}
+
+**Milestone**: [M{N} - Milestone Name](../milestones/milestone-{N}-{name}.md)
+**Estimated Time**: [e.g., "2 hours", "4 hours", "1 day"]
+**Dependencies**: [List prerequisite tasks, or "None"]
+**Status**: Not Started | In Progress | Completed
+
+---
+
+## Objective
+
+[Clearly state what this task accomplishes. Be specific and focused on a single, achievable goal.]
+
+**Example**: "Create the basic project structure with all necessary configuration files and directory organization for a TypeScript-based MCP server."
+
+---
+
+## Context
+
+[Provide background information that helps understand why this task is necessary and how it fits into the larger milestone.]
+
+**Example**: "This task establishes the foundation for the project. Without proper structure and configuration, subsequent development tasks cannot proceed. The structure follows industry best practices for TypeScript projects and MCP server organization."
+
+---
+
+## Steps
+
+[Provide a detailed, sequential list of actions to complete this task. Each step should be concrete and actionable.]
+
+### 1. [Step Category or Action]
+[Detailed description of what to do]
+
+```bash
+# Command examples if applicable
+command --with-flags
+```
+
+```typescript
+// Code examples if applicable
+const example = "code";
+```
+
+### 2. [Next Step]
+[Detailed description]
+
+### 3. [Next Step]
+[Detailed description]
+
+**Example**:
+
+### 1. Create Project Directory
+Create the root directory for the project and navigate into it:
+
+```bash
+mkdir -p my-project
+cd my-project
+```
+
+### 2. Initialize npm Project
+Initialize a new npm project with default settings:
+
+```bash
+npm init -y
+```
+
+### 3. Update package.json
+Edit the generated package.json to include proper metadata and scripts:
+
+```json
+{
+  "name": "my-project",
+  "version": "0.1.0",
+  "description": "Description of what this project does",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.build.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "relevant", "keywords"],
+  "author": "Your Name",
+  "license": "MIT"
+}
+```
+
+### 4. Create Directory Structure
+Create all necessary directories:
+
+```bash
+mkdir -p src/{types,utils,tools}
+mkdir -p tests/{unit,integration}
+mkdir -p agent/{design,milestones,patterns,tasks}
+```
+
+### 5. Create Configuration Files
+Create TypeScript configuration, build scripts, and other config files.
+
+**tsconfig.json**:
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+[Continue with other config files...]
+
+---
+
+## Verification
+
+[Provide a checklist of items to verify the task is complete. Each item should be objectively verifiable.]
+
+- [ ] Verification item 1: [Specific condition to check]
+- [ ] Verification item 2: [Specific condition to check]
+- [ ] Verification item 3: [Specific condition to check]
+- [ ] Verification item 4: [Specific condition to check]
+- [ ] Verification item 5: [Specific condition to check]
+
+**Example**:
+- [ ] Project directory created and contains expected subdirectories
+- [ ] package.json exists and contains correct metadata
+- [ ] tsconfig.json exists and is valid JSON
+- [ ] All configuration files created (.gitignore, .env.example, etc.)
+- [ ] Directory structure matches specification
+- [ ] No syntax errors in configuration files
+
+---
+
+## Expected Output
+
+[Describe what the project should look like after this task is complete.]
+
+**File Structure**:
+```
+project-root/
+├── file1
+├── file2
+└── directory/
+    └── file3
+```
+
+**Key Files Created**:
+- `file1`: [Purpose]
+- `file2`: [Purpose]
+- `directory/file3`: [Purpose]
+
+---
+
+## Common Issues and Solutions
+
+[Document potential problems and how to resolve them:]
+
+### Issue 1: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+### Issue 2: [Problem description]
+**Symptom**: [What the user will see]
+**Solution**: [How to fix it]
+
+**Example**:
+
+### Issue 1: npm init fails
+**Symptom**: Error message about permissions or missing npm
+**Solution**: Ensure Node.js and npm are installed correctly. Run `node --version` and `npm --version` to verify.
+
+### Issue 2: TypeScript configuration errors
+**Symptom**: tsc complains about invalid configuration
+**Solution**: Validate JSON syntax in tsconfig.json. Ensure all required fields are present.
+
+---
+
+## Resources
+
+[Link to relevant documentation, examples, or references:]
+
+- [Resource 1 Name](URL): Description
+- [Resource 2 Name](URL): Description
+- [Resource 3 Name](URL): Description
+
+**Example**:
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/): Official TypeScript documentation
+- [esbuild Documentation](https://esbuild.github.io/): Build tool documentation
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk): MCP protocol reference
+
+---
+
+## Notes
+
+[Any additional context, warnings, or considerations:]
+
+- Note 1: [Important information]
+- Note 2: [Important information]
+- Note 3: [Important information]
+
+**Example**:
+- This task creates the foundation for all subsequent work
+- Configuration files may need adjustment based on specific project requirements
+- Keep .env files out of version control (ensure .gitignore is correct)
+
+---
+
+**Next Task**: [Link to next task: task-{N+1}-{name}.md]
+**Related Design Docs**: [Links to relevant design documents]
+**Estimated Completion Date**: [YYYY-MM-DD or "TBD"]

package/dist/server-factory.js

@@ -786,6 +786,28 @@ function getMemoryCollection(userId) {
   return client2.collections.get(collectionName);
 }
 
+// src/utils/error-handler.ts
+function formatDetailedError(error, context) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : void 0;
+  logger.error(`${context.toolName} failed:`, {
+    error: errorMessage,
+    stack: errorStack,
+    ...context
+  });
+  const contextStr = Object.entries(context).filter(([key]) => key !== "toolName").map(([key, value]) => `${key}=${value}`).join(", ");
+  return `Failed to ${context.operation || "execute"}: ${errorMessage}` + (errorStack ? `
+
+Stack trace:
+${errorStack}` : "") + (contextStr ? `
+
+Context: ${contextStr}` : "");
+}
+function handleToolError(error, context) {
+  const detailedMessage = formatDetailedError(error, context);
+  throw new Error(detailedMessage);
+}
+
 // src/constants/content-types.ts
 var CONTENT_TYPES = [
   // Core types
@@ -1291,8 +1313,13 @@ async function handleCreateMemory(args, userId, context) {
     };
     return JSON.stringify(response, null, 2);
   } catch (error) {
-    logger.error("Failed to create memory:", error);
-    throw new Error(`Failed to create memory: ${error instanceof Error ? error.message : String(error)}`);
+    handleToolError(error, {
+      toolName: "remember_create_memory",
+      operation: "create memory",
+      userId,
+      contentType: args.type,
+      hasContent: !!args.content
+    });
   }
 }
 
@@ -1689,11 +1716,23 @@ async function handleUpdateMemory(args, userId) {
   try {
     logger.info("Updating memory", { userId, memoryId: args.memory_id });
     const collection = getMemoryCollection(userId);
-    const existingMemory = await collection.query.fetchObjectById(args.memory_id, {
-      returnProperties: ["user_id", "doc_type", "version", "type", "weight", "base_weight"]
-    });
+    let existingMemory;
+    try {
+      existingMemory = await collection.query.fetchObjectById(args.memory_id, {
+        returnProperties: ["user_id", "doc_type", "version", "type", "weight", "base_weight"]
+      });
+    } catch (fetchError) {
+      const fetchErrorMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+      logger.error("Failed to fetch memory for update:", {
+        error: fetchErrorMsg,
+        userId,
+        memoryId: args.memory_id,
+        collectionName: `Memory_${userId}`
+      });
+      throw new Error(`Failed to fetch memory ${args.memory_id}: ${fetchErrorMsg}`);
+    }
     if (!existingMemory) {
-      throw new Error(`Memory not found: ${args.memory_id}`);
+      throw new Error(`Memory not found: ${args.memory_id}. It may have been deleted or never existed.`);
     }
     if (existingMemory.properties.user_id !== userId) {
       throw new Error("Unauthorized: Cannot update another user's memory");
@@ -1753,10 +1792,22 @@ async function handleUpdateMemory(args, userId) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     updates.updated_at = now;
     updates.version = existingMemory.properties.version + 1;
-    await collection.data.update({
-      id: args.memory_id,
-      properties: updates
-    });
+    try {
+      await collection.data.update({
+        id: args.memory_id,
+        properties: updates
+      });
+    } catch (updateError) {
+      const updateErrorMsg = updateError instanceof Error ? updateError.message : String(updateError);
+      logger.error("Failed to perform Weaviate update:", {
+        error: updateErrorMsg,
+        userId,
+        memoryId: args.memory_id,
+        updateFields: Object.keys(updates),
+        collectionName: `Memory_${userId}`
+      });
+      throw new Error(`Failed to update memory in Weaviate: ${updateErrorMsg}`);
+    }
     logger.info("Memory updated successfully", {
       userId,
       memoryId: args.memory_id,
@@ -1772,8 +1823,23 @@ async function handleUpdateMemory(args, userId) {
     };
     return JSON.stringify(result, null, 2);
   } catch (error) {
-    logger.error("Failed to update memory:", error);
-    throw new Error(`Failed to update memory: ${error instanceof Error ? error.message : String(error)}`);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorStack = error instanceof Error ? error.stack : void 0;
+    logger.error("Failed to update memory:", {
+      error: errorMessage,
+      stack: errorStack,
+      userId,
+      memoryId: args.memory_id,
+      providedFields: Object.keys(args).filter((k) => k !== "memory_id")
+    });
+    throw new Error(
+      `Failed to update memory: ${errorMessage}` + (errorStack ? `
+
+Stack trace:
+${errorStack}` : "") + `
+
+Context: userId=${userId}, memoryId=${args.memory_id}`
+    );
   }
 }
 

package/dist/server.js

@@ -828,6 +828,28 @@ function getMemoryCollection(userId) {
   return client2.collections.get(collectionName);
 }
 
+// src/utils/error-handler.ts
+function formatDetailedError(error, context) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const errorStack = error instanceof Error ? error.stack : void 0;
+  logger.error(`${context.toolName} failed:`, {
+    error: errorMessage,
+    stack: errorStack,
+    ...context
+  });
+  const contextStr = Object.entries(context).filter(([key]) => key !== "toolName").map(([key, value]) => `${key}=${value}`).join(", ");
+  return `Failed to ${context.operation || "execute"}: ${errorMessage}` + (errorStack ? `
+
+Stack trace:
+${errorStack}` : "") + (contextStr ? `
+
+Context: ${contextStr}` : "");
+}
+function handleToolError(error, context) {
+  const detailedMessage = formatDetailedError(error, context);
+  throw new Error(detailedMessage);
+}
+
 // src/constants/content-types.ts
 var CONTENT_TYPES = [
   // Core types
@@ -1333,8 +1355,13 @@ async function handleCreateMemory(args, userId, context) {
     };
     return JSON.stringify(response, null, 2);
   } catch (error) {
-    logger.error("Failed to create memory:", error);
-    throw new Error(`Failed to create memory: ${error instanceof Error ? error.message : String(error)}`);
+    handleToolError(error, {
+      toolName: "remember_create_memory",
+      operation: "create memory",
+      userId,
+      contentType: args.type,
+      hasContent: !!args.content
+    });
   }
 }
 
@@ -1731,11 +1758,23 @@ async function handleUpdateMemory(args, userId) {
   try {
     logger.info("Updating memory", { userId, memoryId: args.memory_id });
     const collection = getMemoryCollection(userId);
-    const existingMemory = await collection.query.fetchObjectById(args.memory_id, {
-      returnProperties: ["user_id", "doc_type", "version", "type", "weight", "base_weight"]
-    });
+    let existingMemory;
+    try {
+      existingMemory = await collection.query.fetchObjectById(args.memory_id, {
+        returnProperties: ["user_id", "doc_type", "version", "type", "weight", "base_weight"]
+      });
+    } catch (fetchError) {
+      const fetchErrorMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+      logger.error("Failed to fetch memory for update:", {
+        error: fetchErrorMsg,
+        userId,
+        memoryId: args.memory_id,
+        collectionName: `Memory_${userId}`
+      });
+      throw new Error(`Failed to fetch memory ${args.memory_id}: ${fetchErrorMsg}`);
+    }
     if (!existingMemory) {
-      throw new Error(`Memory not found: ${args.memory_id}`);
+      throw new Error(`Memory not found: ${args.memory_id}. It may have been deleted or never existed.`);
     }
     if (existingMemory.properties.user_id !== userId) {
       throw new Error("Unauthorized: Cannot update another user's memory");
@@ -1795,10 +1834,22 @@ async function handleUpdateMemory(args, userId) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     updates.updated_at = now;
     updates.version = existingMemory.properties.version + 1;
-    await collection.data.update({
-      id: args.memory_id,
-      properties: updates
-    });
+    try {
+      await collection.data.update({
+        id: args.memory_id,
+        properties: updates
+      });
+    } catch (updateError) {
+      const updateErrorMsg = updateError instanceof Error ? updateError.message : String(updateError);
+      logger.error("Failed to perform Weaviate update:", {
+        error: updateErrorMsg,
+        userId,
+        memoryId: args.memory_id,
+        updateFields: Object.keys(updates),
+        collectionName: `Memory_${userId}`
+      });
+      throw new Error(`Failed to update memory in Weaviate: ${updateErrorMsg}`);
+    }
     logger.info("Memory updated successfully", {
       userId,
       memoryId: args.memory_id,
@@ -1814,8 +1865,23 @@ async function handleUpdateMemory(args, userId) {
     };
     return JSON.stringify(result, null, 2);
   } catch (error) {
-    logger.error("Failed to update memory:", error);
-    throw new Error(`Failed to update memory: ${error instanceof Error ? error.message : String(error)}`);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorStack = error instanceof Error ? error.stack : void 0;
+    logger.error("Failed to update memory:", {
+      error: errorMessage,
+      stack: errorStack,
+      userId,
+      memoryId: args.memory_id,
+      providedFields: Object.keys(args).filter((k) => k !== "memory_id")
+    });
+    throw new Error(
+      `Failed to update memory: ${errorMessage}` + (errorStack ? `
+
+Stack trace:
+${errorStack}` : "") + `
+
+Context: userId=${userId}, memoryId=${args.memory_id}`
+    );
   }
 }
 

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Centralized error handling utilities for MCP tools
+ * Provides consistent error logging and formatting across all tools
+ */
+/**
+ * Error context for detailed logging
+ */
+export interface ErrorContext {
+    toolName: string;
+    userId?: string;
+    operation?: string;
+    [key: string]: any;
+}
+/**
+ * Format error with detailed context for logging and throwing
+ *
+ * @param error - The caught error
+ * @param context - Additional context about where/why the error occurred
+ * @returns Formatted error message with stack trace and context
+ */
+export declare function formatDetailedError(error: unknown, context: ErrorContext): string;
+/**
+ * Handle tool execution error with detailed logging
+ * Logs the error and throws a formatted error with full context
+ *
+ * @param error - The caught error
+ * @param context - Additional context about the operation
+ * @throws Error with detailed message including stack trace and context
+ */
+export declare function handleToolError(error: unknown, context: ErrorContext): never;
+/**
+ * Wrap an async operation with detailed error handling
+ *
+ * @param operation - The async operation to execute
+ * @param context - Error context for logging
+ * @returns Result of the operation
+ * @throws Error with detailed context if operation fails
+ */
+export declare function withErrorHandling<T>(operation: () => Promise<T>, context: ErrorContext): Promise<T>;
+//# sourceMappingURL=error-handler.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/remember-mcp",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Multi-tenant memory system MCP server with vector search and relationships",
   "main": "dist/server.js",
   "type": "module",