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:

Navigate to your test project:

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

Copy the MCP server files or install as dependency

Generate folder maps:

# Using MCP client, call:
generate_all_folder_maps()

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:

Ensuring directory creation before all file operations
Better error handling with detailed logging
Automatic retry logic for file system operations
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:

File watchers - Update when source files change
Build integration - Generate maps during build process
Git hooks - Update maps on commits
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

Test the system with your Zendesk-ClickUp project
Generate initial maps to see the folder mapping in action
Integrate with your AI workflow using the MCP tools
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.