memory-bank-mcp

Implements read-only access to memory bank files through MCP protocol with path traversal prevention and project-scoped file retrieval. Uses clean architecture layers (Presentation → Domain → Data Access → Infrastructure) to translate MCP read requests into filesystem operations, validating project and file paths against a root directory to prevent unauthorized access. Returns file contents as structured responses with error handling for missing or inaccessible files.

Enables creation of new memory bank files through MCP protocol with comprehensive path validation, project isolation, and file structure enforcement. The Presentation layer validates input parameters, the Domain layer enforces business rules (e.g., valid project and file paths), and the Infrastructure layer performs actual filesystem write operations. Prevents path traversal attacks by validating that resolved paths remain within the target project directory.

Defines data access interfaces that abstract filesystem operations, allowing domain layer to request file operations without knowing implementation details. The Data Access layer specifies interfaces for read, write, update, and list operations, and the Infrastructure layer provides concrete filesystem implementations using Node.js fs module. This abstraction enables testing domain logic with mock implementations and potentially swapping filesystem for other storage backends (cloud storage, databases) without changing domain code.

Implements concrete filesystem operations using Node.js fs module to fulfill data access layer interfaces, handling file reads, writes, updates, and directory listings with proper error handling and path resolution. Performs actual filesystem I/O, manages file permissions, and translates filesystem errors into domain-level error responses. Includes path resolution to normalize paths and prevent directory traversal, and handles edge cases like missing files, permission errors, and invalid paths.

Configures memory bank root directory through MEMORY_BANK_ROOT environment variable, enabling deployment flexibility without code changes. The server reads this variable at startup to determine where all project directories are located, allowing different deployments (development, staging, production) to use different filesystem locations. Supports Docker deployment where the environment variable can be set via container environment or volume mounts.

Defines type-safe operation schemas for each MCP tool with explicit input parameters, output types, and validation rules. Each operation specifies required parameters (project_id, file_path, contents), their types (string, etc.), and validation constraints. The Presentation layer validates incoming requests against these schemas before passing to domain logic, ensuring type safety and preventing invalid inputs from reaching business logic. Supports MCP tool definition format with parameter descriptions and types.

Provides in-place update capability for existing memory bank files through MCP protocol, replacing entire file contents while maintaining project isolation and path safety. Uses the same clean architecture pattern as file creation but targets existing files, with validation ensuring the file exists before update and the resolved path remains within project boundaries. Supports overwriting memory bank entries with new content from AI agents.

Lists all available projects in the memory bank root directory through MCP protocol, enabling clients to discover project structure without filesystem access. Implements read-only enumeration at the Presentation layer that queries the Infrastructure layer's filesystem operations to return project directories, with implicit filtering to exclude non-directory entries and hidden files. Supports multi-project management by allowing clients to discover which projects are available before accessing their files.

Lists all files within a specific project directory through MCP protocol, enabling clients to discover available memory bank files without direct filesystem access. Validates the project_id parameter to ensure it exists and resolves to a valid path within MEMORY_BANK_ROOT, then enumerates files in that project directory. Returns file names (not full paths) to maintain abstraction, with implicit filtering of directories and hidden files. Supports memory bank exploration by allowing clients to discover which files are available in a project.

Implements the Presentation layer that translates incoming MCP protocol requests into domain operations and formats responses back to MCP format. Acts as an adapter between the MCP protocol's request/response structure and the internal domain layer's use cases, performing input validation, parameter extraction, and response formatting. Each MCP tool (memory_bank_read, memory_bank_write, etc.) maps to a corresponding use case through this translation layer, ensuring type safety and consistent error handling across all operations.

Implements security validation across the architecture to prevent directory traversal attacks by resolving file paths to absolute paths and verifying they remain within the target project directory. The Presentation layer validates input format, the Domain layer enforces business rules, and the Infrastructure layer performs final resolved-path verification before filesystem operations. Uses filesystem path resolution (e.g., Node.js path.resolve) to normalize paths containing '..' or symbolic links, then validates the resolved path is within the project root using string prefix matching or path comparison.

Enforces project boundaries by organizing memory banks into separate project directories under MEMORY_BANK_ROOT and validating all file operations against the target project directory. Each project is a subdirectory containing its own memory bank files, and all read/write operations validate that the resolved file path remains within the project directory. This isolation is enforced at the Infrastructure layer through filesystem operations and validated at the Presentation and Domain layers, preventing clients from accessing files in other projects.

Implements a complete MCP server that exposes five core tools (memory_bank_read, memory_bank_write, memory_bank_update, list_projects, list_project_files) through the Model Context Protocol, enabling MCP-compatible clients like Claude, Cursor, and Cline to interact with memory banks. The server defines tool schemas with input parameters and output types, handles MCP protocol messages, and routes requests to appropriate handlers. Provides type-safe operation definitions and proper error responses conforming to MCP specification.

Implements domain layer use cases that encapsulate business logic for each operation (read, write, update, list projects, list files) independent of MCP protocol or filesystem details. Each use case defines the business rules and constraints for its operation, receives validated inputs from the Presentation layer, and delegates to Data Access layer interfaces for actual operations. Use cases are protocol-agnostic and could be reused with different interfaces (REST, gRPC, CLI), enabling clean separation of concerns and testability.