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

npm install

2. Test the System

node test-memory.js

3. Build the Project

npm run build

4. Run the MCP Server

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:

# ⚙️ 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:

   cd D:\Development\Projects\Products\zendesk-clickup-automation
   

2. Copy the MCP server files or install as dependency

3. Generate folder maps:

   # 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:

# 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:

# 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:

# Check TypeScript parsing dependencies
npm install @typescript-eslint/typescript-estree

# Verify src directory exists
# Check file permissions

MCP Connection Issues:

# 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.