MCP Server Memo

MCP Server Memo

一个轻量级 MCP（Model Context Protocol）服务，用于管理 Claude 等大模型的丰富会话摘要和备忘录。此服务使用本地文件系统提供持久化存储，支持会话历史版本跟踪，并提供存储、检索和列出摘要的工具。

概览

MCP Server Memo 是一款面向大模型的记忆助手，允许它们通过 MCP 工具接口存储和检索详细的会话记录。此服务：

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

安装

# Clone the repository
git clone https://github.com/doggybee/mcp-server-memo.git
cd mcp-server-memo

# Install dependencies
npm install

# Build the project
npm run build

配置

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

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

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

export MCP_SUMMARY_DIR="/path/to/summaries"

运行服务

# Standard startup
npm start

# Development mode (with auto-reload)
npm run dev

# Start with logging to file
npm run start:log

MCP 工具

此服务提供以下 MCP 工具：

1. upsertSummary

创建会话摘要的新版本，但不删除之前的版本。

参数：

• sessionId（string，必填）：对话会话的唯一标识符。生成此 ID 是客户端应用程序的责任。 应在新的逻辑对话会话开始时生成一次。建议： 使用编程语言中提供的标准 UUID（版本 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（字符串，必需）：要更新元数据的会话唯一 ID。
• title（字符串，可选）：新标题。如果省略，标题保持不变。
• tags（字符串数组，可选）：新标签数组。如果省略，标签保持不变。

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

行为：

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

5. appendSummary

向会话摘要追加内容，并创建一个包含先前内容和新增内容的新版本。

参数：

• sessionId（字符串，必需）：对话会话的唯一标识符。
• content（字符串，必需）：要追加到会话中的内容。此内容将添加到现有内容中，并保存为新版本。
• title（字符串，可选）：会话的可选标题。
• tags（字符串数组，可选）：用于对会话分类的可选标签。

行为：

• 读取现有的最新摘要（如果有）
• 在内容之间添加两个换行符，然后追加新内容
• 使用新的时间戳创建新文件
• 保留所有先前版本

6. listAllSummariesTool

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

参数：

• 无

返回：

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

7. getSessionHistory

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

参数：

• sessionId（字符串，必需）：要检索历史记录的会话唯一 ID。

返回：

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

客户端工作流示例

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

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

// Initialize client
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);

// Function to generate new session ID (done once per logical session)
function createNewSession() {
  return uuidv4();
}

// Function to append to an existing session
async function appendToSession(sessionId, newContent) {
  return client.callTool({
    name: "appendSummary",
    arguments: {
      sessionId,
      content: newContent,
      title: "Example Session",
      tags: ["example", "demo"]
    }
  });
}

// Function to get session history
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");
}

// Usage example
const sessionId = createNewSession();

// Add initial content
await appendToSession(sessionId, "Initial conversation data");

// Add more content later in the conversation
await appendToSession(sessionId, "Second part of the conversation");
await appendToSession(sessionId, "Final part of the conversation");

// Get the full history
const history = await getSessionHistory(sessionId);
console.log(`Session ${sessionId} has ${history.length} versions`);

项目结构

mcp-server-memo/
├── dist/                 # Compiled JavaScript output
├── src/                  # TypeScript source code
│   ├── config.ts         # Server configuration
│   ├── index.ts          # Main entry point
│   ├── storage.ts        # File storage utilities
│   ├── tools.ts          # MCP tool implementations
│   └── types.ts          # TypeScript type definitions
├── summaries/            # Directory for storing session data
│   └── .gitkeep          # Ensures directory is included in git
├── package.json          # Project metadata and dependencies
├── tsconfig.json         # TypeScript configuration
└── LICENSE               # MIT License file

许可证

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