MCP Memory Server

# MCP Memory Server with Folder Mapping A comprehensive MCP (Model Context Protocol) server that provides AI coding assistants with memory management, file approval tracking, changelog functionality, and **automatic folder mapping**. ## 🆕 New Features Added ### 📁 **Folder Mapping System** Automatically generates `_map.md` files for each folder in your project, providing quick overviews of: - Classes, interfaces, functions, and types - Method signatures and parameters - File purposes and relationships - Dependencies and test locations - Risk assessments This solves the problem of **code discoverability** - helping both AI agents and developers quickly understand what's available without diving into every file. ## 🚀 Quick Start ### 1. Install Dependencies ```bash npm install ``` ### 2. Test the System ```bash node test-memory.js ``` ### 3. Build the Project ```bash npm run build ``` ### 4. Run the MCP Server ```bash npm start ``` ## 🛠️ Available MCP Tools ### Memory Management - `start_session(task)` - Start a new coding session - `add_session_step(step, filesModified, description?)` - Record completed work - `add_decision(key, value, reasoning)` - Record important decisions - `get_project_memory()` - Get current project state ### File Approvals - `set_file_approval(filePath, approvalType, approvedBy)` - Set approval status - `get_file_approval_status(filePath)` - Check approval status - `check_before_modification(filePath)` - Validate before changes - `get_modification_actions(filePath)` - Get post-change actions ### 📁 **Folder Mapping (NEW)** - `generate_folder_map(folderPath)` - Generate `_map.md` for specific folder - `generate_all_folder_maps()` - Generate maps for all project folders - `update_folder_map_if_needed(filePath)` - Update map if files changed - `find_all_map_files()` - List all existing map files - `validate_all_maps()` - Check if maps are up-to-date ### Metadata & Changelog - `parse_file_metadata(filePath)` - Extract AI metadata from files - `update_file_metadata(filePath, updates)` - Update file metadata - `add_changelog_entry(...)` - Add changelog entry - `get_recent_changes(days?)` - Get recent project changes ## 📋 Folder Map Example When you run `generate_folder_map("src/services")`, it creates `src/services/_map.md`: ```markdown # ⚙️ services Module Map > **Purpose**: Business logic and external service integrations ## 📊 Quick Stats - **Files**: 4 - **Classes**: 3 - **Interfaces**: 2 - **Functions**: 8 ## 🗂️ Files Overview ### `user-service.ts` **Purpose**: User management and authentication | **Risk**: medium **CLASS**: `UserService` - `authenticateUser(credentials)` - Validates user credentials - `getUserProfile(userId)` - Retrieves user profile data - `updateUserSettings(userId, settings)` - Updates user preferences ### `api-client.ts` **Purpose**: HTTP client for external APIs | **Risk**: high **CLASS**: `ApiClient` - `get(url, options?)` - HTTP GET request - `post(url, data, options?)` - HTTP POST request - `handleError(error)` - Centralized error handling ## 🔗 Dependencies - `../types/user-types.ts` - `../utils/http-utils.ts` ## 🧪 Tests - `tests/services/user-service.test.ts` - `tests/services/api-client.test.ts` ``` ## 🔧 Integration with Your Test Project ### For your Zendesk-ClickUp automation project: 1. **Navigate to your test project**: ```bash cd D:\Development\Projects\Products\zendesk-clickup-automation ``` 2. **Copy the MCP server files** or **install as dependency** 3. **Generate folder maps**: ```bash # Using MCP client, call: generate_all_folder_maps() ``` 4. **Your folder structure will get maps**: ``` src/ ├── agents/ │ └── _map.md ← Overview of all agent classes ├── services/ │ └── _map.md ← Service integrations overview ├── types/ │ └── _map.md ← All TypeScript definitions └── utils/ └── _map.md ← Utility functions overview ``` ## 🛡️ Memory Recording Fix The memory recording issues have been fixed by: 1. **Ensuring directory creation** before all file operations 2. **Better error handling** with detailed logging 3. **Automatic retry logic** for file system operations 4. **Proper async/await** patterns throughout ## 💡 Benefits for AI Agents ### Before Folder Mapping: - AI has to read every file to understand what's available - Often creates duplicate functionality - Slow to understand project structure - Poor code reuse suggestions ### After Folder Mapping: - **Instant project comprehension** from `_map.md` files - **Prevents duplicate code** - AI sees what already exists - **Better suggestions** - AI knows available methods and classes - **Faster development** - Quick navigation and understanding ## 📖 Usage in AI Workflows ### Typical AI Session: ```bash # 1. Start a session start_session("Add user authentication feature") # 2. Generate/update maps to understand codebase generate_all_folder_maps() # 3. AI reads maps to understand existing code # 4. AI writes new code using existing patterns # 5. Record progress add_session_step("Created UserAuth class", ["src/auth/user-auth.ts"], "Implemented JWT-based authentication") # 6. Update relevant maps update_folder_map_if_needed("src/auth/user-auth.ts") ``` ## 🎯 Best Practices ### For AI Agents: - Always read relevant `_map.md` files before suggesting new code - Use `update_folder_map_if_needed()` after creating/modifying files - Check existing functionality to avoid duplication ### For Developers: - Review generated maps for accuracy - Update maps when adding major new features - Use maps for onboarding new team members ## 🔄 Auto-Update Strategy Maps can be kept current by: 1. **File watchers** - Update when source files change 2. **Build integration** - Generate maps during build process 3. **Git hooks** - Update maps on commits 4. **CI/CD integration** - Validate maps in pipelines ## 🚨 Troubleshooting ### Memory Not Recording: ```bash # Run the test script node test-memory.js # Check for errors in .ai-memory folder creation # Ensure proper permissions on project directory ``` ### Maps Not Generating: ```bash # Check TypeScript parsing dependencies npm install @typescript-eslint/typescript-estree # Verify src directory exists # Check file permissions ``` ### MCP Connection Issues: ```bash # Rebuild the project npm run build # Check MCP client configuration # Verify server is running on correct port ``` ## 📚 Next Steps 1. **Test the system** with your Zendesk-ClickUp project 2. **Generate initial maps** to see the folder mapping in action 3. **Integrate with your AI workflow** using the MCP tools 4. **Customize map templates** if needed for your specific patterns The folder mapping feature transforms how AI agents understand and work with your codebase, making them far more effective at code reuse and avoiding duplication.