MCP服务器备忘录

一个轻量级的MCP（模型上下文协议）服务器，用于管理像Claude这样的大型语言模型的丰富会话摘要和备忘录。该服务器使用本地文件系统提供持久存储，支持会话历史版本跟踪，并提供用于存储、检索和列出摘要的工具。

概述

MCP服务器备忘录被设计为大型语言模型的记忆助手，允许它们通过MCP工具接口存储和检索详细的会话记录。该服务器：

• 保留历史记录 - 保留会话的所有历史版本（相同的sessionId），而不仅仅是最新版本
• 按时间排序 - 会话的多个版本按时间顺序组织，便于跟踪对话发展
• 本地存储 - 使用本地文件系统，无需外部数据库
• 符合MCP标准 - 遵循模型上下文协议规范以提供工具接口
• 性能优化 - 针对文件I/O和并发操作进行了优化
• 最小依赖 - 简洁的设计，易于维护和扩展

安装

# 克隆仓库
git clone https://github.com/doggybee/mcp-server-memo.git
cd mcp-server-memo

# 安装依赖
npm install

# 构建项目
npm run build

配置

服务器使用以下配置选项：

• MCP_SUMMARY_DIR: 用于存储摘要的目录（默认值：./summaries/）

您可以通过环境变量设置这些选项：

export MCP_SUMMARY_DIR="/path/to/summaries"

运行服务器

# 标准启动
npm start

# 开发模式（自动重新加载）
npm run dev

# 启动并记录到文件
npm run start:log

MCP工具

服务器提供以下MCP工具：

1. upsertSummary

创建一个会话摘要的新版本，而不删除以前的版本。

参数：

• sessionId (string, 必需): 会话的唯一标识符。客户端应用程序负责生成此ID。 它应该在新逻辑会话开始时生成一次。 建议： 使用编程语言中可用的标准 UUID (Version 4) 库以确保唯一性。 客户端必须为与该特定会话相关的所有后续 upsertSummary 调用重复使用相同的生成的ID。
• summary (string, 必需): 会话编年史/日志的详细内容。 每次调用都会在会话历史记录中创建一个新版本，而不是覆盖以前的版本。
• title (string, 可选): 会话的简短描述性标题。
• tags (string[], 可选): 用于对会话进行分类的关键字或标签。

行为：

• 创建一个带有新时间戳的新文件
• 保留所有以前的版本
• 返回新版本的时间戳

2. getSummaryTool

检索特定会话摘要的最新版本。

参数：

• sessionId (string, 必需): 要检索的会话摘要的唯一ID。
• maxLength (number, 可选): 如果提供，则将检索到的摘要文本截断为此最大长度。

返回：

• 最新的会话摘要对象（JSON格式）

3. listSummariesTool

列出可用的摘要（仅每个会话的最新版本），支持过滤、排序和分页。

参数：

• tag (string, 可选): 按特定标签过滤会话。
• limit (number, 可选): 限制结果数量。
• offset (number, 可选): 分页偏移量。
• sortBy (string, 可选): 排序字段（'lastUpdated' 或 'title'）。 默认值：'lastUpdated'。
• order (string, 可选): 排序顺序（'asc' 或 'desc'）。 默认值：'desc'。

返回：

• 摘要元数据对象列表（JSON格式），仅包含每个会话的最新版本

4. updateMetadata

仅更新会话最新版本的元数据（标题和/或标签），而不更改摘要内容或时间戳。

参数：

• sessionId (string, 必需): 要更新其元数据的会话的唯一ID。
• title (string, 可选): 新标题。 如果省略，标题保持不变。
• tags (string[], 可选): 新标签数组。 如果省略，标签保持不变。

注意： 必须提供 title 或 tags 中的至少一个。

行为：

• 不更新文件名中的时间戳或 lastUpdated 字段
• 仅修改指定的元数据字段
• 不影响摘要内容

5. appendSummary

将内容附加到会话摘要，创建一个包含先前内容和新内容的新版本。

参数：

• sessionId (string, 必需): 会话的唯一标识符。
• content (string, 必需): 要附加到会话的内容。 这将被添加到现有内容并保存为新版本。
• title (string, 可选): 会话的可选标题。
• tags (string[], 可选): 用于对会话进行分类的可选标签。

行为：

• 读取现有的最新摘要（如果有）
• 在内容之间添加两个换行符并附加新内容
• 创建一个带有新时间戳的新文件
• 保留所有以前的版本

6. listAllSummariesTool

列出所有可用的摘要，包含基本信息（仅每个会话的最新版本）。

参数：

• 无

返回：

• 所有可用摘要的列表，包含基本信息（JSON格式）

7. getSessionHistory

检索特定会话的所有历史版本，从最新到最旧排序。

参数：

• sessionId (string, 必需): 要检索历史记录的会话的唯一ID。

返回：

• 所有版本的列表，包含完整内容（JSON格式）

客户端工作流程示例

以下是客户端应用程序如何与此服务器交互的示例：

import { v4 as uuidv4 } from 'uuid';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// 初始化客户端
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  cwd: process.cwd()
});

const client = new Client({
  name: 'example-client',
  version: '1.0.0'
});

await client.connect(transport);

// 用于生成新会话ID的函数（每个逻辑会话执行一次）
function createNewSession() {
  return uuidv4();
}

// 用于附加到现有会话的函数
async function appendToSession(sessionId, newContent) {
  return client.callTool({
    name: "appendSummary",
    arguments: {
      sessionId,
      content: newContent,
      title: "Example Session",
      tags: ["example", "demo"]
    }
  });
}

// 用于获取会话历史记录的函数
async function getSessionHistory(sessionId) {
  const response = await client.callTool({
    name: "getSessionHistory",
    arguments: { sessionId }
  });
  
  const result = JSON.parse(response.content[0].text);
  if (result.success) {
    return result.history;
  }
  
  throw new Error(result.error || "Failed to get session history");
}

// 用法示例
const sessionId = createNewSession();

// 添加初始内容
await appendToSession(sessionId, "Initial conversation data");

// 在对话的稍后阶段添加更多内容
await appendToSession(sessionId, "Second part of the conversation");
await appendToSession(sessionId, "Final part of the conversation");

// 获取完整历史记录
const history = await getSessionHistory(sessionId);
console.log(`Session ${sessionId} has ${history.length} versions`);

项目结构

mcp-server-memo/
├── dist/                 # 编译后的JavaScript输出
├── src/                  # TypeScript源代码
│   ├── config.ts         # 服务器配置
│   ├── index.ts          # 主入口点
│   ├── storage.ts        # 文件存储实用程序
│   ├── tools.ts          # MCP工具实现
│   └── types.ts          # TypeScript类型定义
├── summaries/            # 用于存储会话数据的目录
│   └── .gitkeep          # 确保目录包含在git中
├── package.json          # 项目元数据和依赖项
├── tsconfig.json         # TypeScript配置
└── LICENSE               # MIT许可证文件

许可证

该项目根据MIT许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。