内存库 MCP 服务器

一个基于模型上下文协议（MCP）的远程内存库管理服务器实现，灵感来源于 Cline Memory Bank。

概述

Memory Bank MCP 服务器将传统的基于文件的内存库转换为集中式服务，具备以下功能：

• 通过 MCP 协议提供对内存库文件的远程访问
• 支持多项目内存库管理
• 维护一致的文件结构和验证机制
• 确保各项目内存库之间的适当隔离

功能特性

• 多项目支持

  • 项目专用目录
  • 文件结构强制执行
  • 防止路径遍历攻击
  • 项目列表功能
  • 按项目列出文件

• 远程可访问性

  • 完整的 MCP 协议实现
  • 类型安全的操作
  • 合理的错误处理
  • 通过项目隔离确保安全性

• 核心操作

  • 读取/写入/更新内存库文件
  • 列出可用项目
  • 列出项目中的文件
  • 验证项目是否存在
  • 安全的只读操作

安装

要通过 Smithery 自动安装用于 Claude Desktop 的 Memory Bank 服务器：

npx -y @smithery/cli install @alioshr/memory-bank-mcp --client claude

这将自动设置 MCP 服务器配置。或者，您也可以按照下面的“配置”部分手动配置服务器。

快速入门

1. 在您的设置中配置 MCP 服务器（参见下方的“配置”部分）
2. 开始在您的 AI 助手中使用内存库工具

与 Cline/Roo Code 配合使用

Memory Bank MCP 服务器需要在您的 Cline MCP 设置文件中进行配置。具体位置取决于您的设置：

• 对于 Cline 扩展：~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• 对于 Roo Code VS Code 扩展：~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

将以下配置添加到您的 MCP 设置中：

{
  "allpepper-memory-bank": {
    "command": "npx",
    "args": ["-y", "@allpepper/memory-bank-mcp"],
    "env": {
      "MEMORY_BANK_ROOT": "<path-to-bank>"
    },
    "disabled": false,
    "autoApprove": [
      "memory_bank_read",
      "memory_bank_write",
      "memory_bank_update",
      "list_projects",
      "list_project_files"
    ]
  }
}

配置详情

• MEMORY_BANK_ROOT：存储项目内存库的目录（例如 /path/to/memory-bank）
• disabled：设置为 false 以启用服务器
• autoApprove：无需用户明确批准的操作列表：
  • memory_bank_read：读取内存库文件
  • memory_bank_write：创建新的内存库文件
  • memory_bank_update：更新现有内存库文件
  • list_projects：列出可用项目
  • list_project_files：列出项目中的文件

与 Cursor 配合使用

对于 Cursor，请打开设置 -> 功能 -> 添加 MCP 服务器 -> 添加以下内容：

env MEMORY_BANK_ROOT=<path-to-bank> npx -y @allpepper/memory-bank-mcp@latest

与 Claude 配合使用

• Claude 桌面配置文件：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code 配置文件：~/.claude.json

1. 找到配置文件
2. 找到名为 mcpServers 的属性
3. 粘贴以下内容：

 "allPepper-memory-bank": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "@allpepper/memory-bank-mcp@latest"
          ],
          "env": {
            "MEMORY_BANK_ROOT": "YOUR PATH"
          }
        }

自定义 AI 指令

本节包含应粘贴到 AI 自定义指令中的指令，适用于 Cline、Claude 或 Cursor，以及其他任何 MCP 客户端。您应该复制并粘贴这些规则。有关参考，请参阅 custom-instructions.md，其中包含了这些规则。

开发

基本开发命令：

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm run test

# 监视模式下运行测试
npm run test:watch

# 使用 ts-node 直接运行服务器以快速测试
npm run dev

使用 Docker 运行

1. 构建 Docker 镜像：

   docker build -t memory-bank-mcp:local .
   

2. 运行 Docker 容器进行测试：

   docker run -i --rm \
     -e MEMORY_BANK_ROOT="/mnt/memory_bank" \
     -v /path/to/memory-bank:/mnt/memory_bank \
     --entrypoint /bin/sh \
     memory-bank-mcp:local \
     -c "ls -la /mnt/memory_bank"
   

3. 添加 MCP 配置，例如针对 Roo Code：

   "allpepper-memory-bank": {
     "command": "docker",
     "args": [
       "run", "-i", "--rm",
       "-e", 
       "MEMORY_BANK_ROOT",
       "-v", 
       "/path/to/memory-bank:/mnt/memory_bank",
       "memory-bank-mcp:local"
     ],
     "env": {
       "MEMORY_BANK_ROOT": "/mnt/memory_bank"
     },
     "disabled": false,
     "alwaysAllow": [
       "list_projects",
       "list_project_files",
       "memory_bank_read",
       "memory_bank_update",
       "memory_bank_write"
     ]
   }
   

贡献

欢迎贡献！请按照以下步骤操作：

1. 分支仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加惊人功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 所有新代码均使用 TypeScript
• 维护整个代码库的类型安全性
• 为新功能添加测试
• 根据需要更新文档
• 遵循现有代码风格和模式

测试

• 为新功能编写单元测试
• 包含多项目场景测试
• 彻底测试错误情况
• 验证类型约束
• 适当地模拟文件系统操作

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

致谢

本项目实现了最初在Cline Memory Bank中记录的记忆库概念，并在此基础上扩展了远程功能和多项目支持。

Memory Bank MCP 快速上手指南

Memory Bank MCP Server 是一个基于模型上下文协议（MCP）的服务端实现，旨在将传统的基于文件的记忆库（Memory Bank）转化为集中式服务。它支持多项目管理、远程访问以及严格的文件结构验证，特别适用于 Cline、Roo Code 和 Cursor 等 AI 编程助手。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS, Linux 或 Windows (WSL)
• Node.js：建议安装 LTS 版本（v18 或更高），用于运行 npx 命令。
  • 检查版本：node -v
• AI 客户端：已安装并配置好支持 MCP 的客户端（如 Claude Desktop, Cline, Roo Code, 或 Cursor）。
• 存储目录：规划一个本地目录用于存放记忆库文件（例如：~/projects/memory-bank）。

安装步骤

您可以选择通过 Smithery 自动安装，或手动配置 MCP 服务器。

方式一：使用 Smithery 自动安装（推荐）

如果您使用 Claude Desktop，可以通过 Smithery CLI 一键安装：

npx -y @smithery/cli install @alioshr/memory-bank-mcp --client claude

该命令会自动下载包并更新您的配置文件。

方式二：手动配置

如果自动安装不适用，或您需要自定义配置（如指定存储路径），请按以下步骤操作：

1. 找到配置文件：

   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)
   • Cline (VS Code): ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Roo Code (VS Code): ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
   • Cursor: 设置 -> Features -> MCP Servers -> Add New

2. 添加服务器配置： 在配置文件的 mcpServers 对象中添加以下内容。请将 <path-to-bank> 替换为您实际规划的存储目录绝对路径。

   "allpepper-memory-bank": {
     "command": "npx",
     "args": ["-y", "@allpepper/memory-bank-mcp@latest"],
     "env": {
       "MEMORY_BANK_ROOT": "<path-to-bank>"
     },
     "disabled": false,
     "autoApprove": [
       "memory_bank_read",
       "memory_bank_write",
       "memory_bank_update",
       "list_projects",
       "list_project_files"
     ]
   }
   

   注：对于 Cursor，也可以在添加服务器时直接输入命令：env MEMORY_BANK_ROOT=<path-to-bank> npx -y @allpepper/memory-bank-mcp@latest

3. 重启客户端：保存配置文件并重启您的 AI 编辑器或桌面应用以加载新配置。

基本使用

配置完成后，Memory Bank MCP 服务器将在后台运行。您无需直接运行命令，而是通过与 AI 助手对话来管理记忆库。

1. 创建或列出项目

在聊天窗口中询问 AI：

"列出所有可用的记忆库项目。" "为我的新项目 'my-app' 创建一个记忆库。"

AI 将调用 list_projects 或 memory_bank_write 工具来执行操作。

2. 读写记忆文件

针对特定项目进行文档管理：

"在 'my-app' 项目中读取 product-context.md 文件。" "更新 'my-app' 项目的 progress.md，记录今天完成了登录功能。"

AI 会自动调用 memory_bank_read 或 memory_bank_update 工具，确保文件结构符合规范。

3. 查看项目文件列表

"显示 'my-app' 项目中所有的记忆文件。"

这将触发 list_project_files 工具，帮助您了解当前项目的文档结构。

提示

• 自动批准：配置中的 autoApprove 列表允许 AI 直接执行读写操作而无需每次确认，提升了流畅度。如需更高安全性，可从列表中移除相应权限。
• 隔离性：不同项目的记忆库存储在独立的子目录中，互不干扰。