Recap

一个基于 Express 的 MCP (Model Context Protocol) 服务器，用于对话记录和回顾管理。

功能特性

• 📝 对话记录工具 - 记录、查询和管理对话历史
• 🌐 双传输模式 - 支持 stdio 和 HTTP 传输
• 💾 文件系统存储 - 基于 JSON 文件的本地存储
• 🏷️ 标签管理 - 支持对话标签分类和搜索
• 📊 统计分析 - 提供对话统计和趋势分析
• 🎯 TypeScript 优先 - 完整的类型安全支持
• 🚀 Express 集成 - 提供 RESTful API 端点

安装和运行

前置要求

• Node.js 18+
• pnpm 8+

快速开始

# 克隆项目
git clone <repository-url>
cd recap

# 安装依赖
pnpm install

# 开发模式运行 (stdio transport)
pnpm run dev

# 或者以 HTTP 模式运行
pnpm run dev http 3001

构建和部署

# 构建项目
pnpm run build

# 运行生产版本 (stdio transport)
pnpm start

# 或者以 HTTP 模式运行
pnpm start http 3001

可用工具

1. 对话记录工具 (conversation_recorder)

记录、查询和管理对话历史记录。

参数：

• conversationContent (string): 需要记录的对话内容
• action (enum): 操作类型 - record, query, stats
• metadata (object, 可选): 包含标题、参与者、持续时间和对话类型
• tags (array, 可选): 对话标签数组
• summary (string, 可选): 对话摘要 - "今天聊了什么"
• thoughts (string, 可选): 个人想法 - "我觉得..."
• factual_notes (string, 可选): 事实记录 - "发生了什么事"
• queryParams (object, 可选): 查询参数，用于查询历史记录

支持的对话类型：

• 技术讨论 (technical_discussion)
• 问题解决 (problem_solving)
• 创意头脑风暴 (creative_brainstorming)
• 教育 (educational)
• 休闲聊天 (casual_chat)
• 计划 (planning)
• 审查反馈 (review_feedback)
• 其他 (other)

示例：

记录对话：

{
  "name": "conversation_recorder",
  "arguments": {
    "conversationContent": "今天我们讨论了项目的进展，需要在下周完成设计稿的修改。",
    "action": "record",
    "metadata": {
      "title": "项目进展讨论",
      "participants": ["小明", "小红"],
      "duration": 30,
      "conversationType": "technical_discussion"
    },
    "tags": ["项目", "设计"],
    "summary": "讨论了项目进展和设计稿修改计划",
    "thoughts": "项目时间有点紧张，需要合理安排任务",
    "factual_notes": "确定在下周完成设计稿修改"
  }
}

查询历史记录：

{
  "name": "conversation_recorder",
  "arguments": {
    "conversationContent": "",
    "action": "query",
    "queryParams": {
      "type": "by_tags",
      "tags": ["项目"]
    }
  }
}

获取统计信息：

{
  "name": "conversation_recorder",
  "arguments": {
    "conversationContent": "",
    "action": "stats"
  }
}

API 端点

当以 HTTP 模式运行时，服务器提供以下端点：

管理端点

• GET /health - 健康检查
• GET /mcp/status - MCP 服务器状态信息和可用工具列表

MCP 协议端点

• ALL /mcp - Streamable HTTP 传输

所有 MCP 工具都可以通过这些端点访问，包括 conversation_recorder。

数据存储

• 对话记录存储在 data/conversations/ 目录下
• 每个对话记录保存为独立的 JSON 文件
• 索引文件 index.json 用于快速查询和统计
• 支持按标签、时间范围、对话类型等多种方式查询

传输模式

Stdio Transport (默认)

pnpm start

HTTP Transport

pnpm start http 3001

HTTP 模式提供了完整的 MCP 协议支持：

• Streamable HTTP - 协议版本 2025-03-26
  • 端点: /mcp
  • 支持完整的 MCP 会话管理
  • 使用单一端点处理所有 MCP 请求

详细的 HTTP 模式使用指南请参考 HTTP_USAGE.md

Docker 部署

快速启动

# 构建和启动服务 (HTTP 模式)
docker-compose up -d

# 查看日志
docker-compose logs -f recap-mcp

# 停止服务
docker-compose down

访问服务

• 健康检查: http://localhost:3001/health
• MCP 状态: http://localhost:3001/mcp/status
• MCP 协议端点: http://localhost:3001/mcp

数据持久化

对话数据将自动保存到本地 ./data 目录，即使容器重启也不会丢失数据。

详细的 Docker 使用指南请参考 DOCKER_USAGE.md

GitHub Actions 自动化

项目配置了 GitHub Actions workflow 来自动构建和推送 Docker 镜像：

自动触发条件

• Push 到 main/master 分支 - 构建并推送到 Docker Hub
• 创建版本标签 (如 v1.0.0) - 构建并推送带版本标签的镜像
• Pull Request - 仅构建镜像进行测试，不推送

使用发布的镜像

# 拉取最新镜像
docker pull eric8810/recap-mcp-server:latest

# 拉取特定版本
docker pull eric8810/recap-mcp-server:v1.0.0

# 运行容器
docker run -d \
  --name recap-mcp \
  -p 3001:3001 \
  -v $(pwd)/data:/app/data \
  eric8810/recap-mcp-server:latest \
  node dist/index.js http 3001

配置说明

要使用 GitHub Actions 自动化：

1. 在 GitHub 仓库中设置 Docker Hub 凭证
2. 修改 workflow 文件中的镜像名称
3. 推送代码或创建版本标签即可自动构建

详细配置指南请参考 GITHUB_ACTIONS.md

项目结构

recap/
├── src/
│   ├── tools/              # 工具定义
│   │   └── ConversationTool.ts
│   ├── storage/            # 存储实现
│   │   └── FileStorage.ts
│   ├── types/              # 类型定义
│   │   └── ConversationRecord.ts
│   ├── resources/          # 资源定义 (预留)
│   ├── prompts/            # 提示定义 (预留)
│   └── index.ts            # 主服务器文件
├── data/                   # 数据存储目录
│   └── conversations/      # 对话记录存储
├── debug/                  # 调试脚本
├── dist/                   # 构建输出
├── package.json            # 项目配置
├── tsconfig.json           # TypeScript 配置
└── README.md               # 项目文档

开发指南

添加新工具

1. 在 src/tools/ 目录下创建新工具文件
2. 使用 Zod 定义工具的输入架构
3. 实现工具的执行逻辑
4. 在 src/index.ts 中导入并注册工具

示例工具结构

import { z } from "zod";

export const MyToolSchema = z.object({
  input: z.string().describe("工具输入描述"),
  action: z.enum(["create", "update", "delete"]).describe("操作类型"),
});

export class MyTool {
  static readonly name = "my_tool";
  static readonly description = "工具描述";
  static readonly schema = MyToolSchema;

  static async execute(input: z.infer<typeof MyToolSchema>) {
    // 实现工具逻辑
    try {
      // 处理业务逻辑
      const result = await this.processInput(input);

      return {
        type: "text",
        text: `处理结果: ${result}`,
      };
    } catch (error) {
      return {
        type: "text",
        text: `处理失败: ${
          error instanceof Error ? error.message : "未知错误"
        }`,
      };
    }
  }

  private static async processInput(input: z.infer<typeof MyToolSchema>) {
    // 具体的处理逻辑
    return `已执行 ${input.action} 操作`;
  }
}

扩展存储功能

如果需要添加新的存储后端，可以实现 ConversationStorage 接口：

import { ConversationStorage } from "./types/ConversationRecord.js";

export class MyStorage implements ConversationStorage {
  async save(record: ConversationRecord): Promise<void> {
    // 实现保存逻辑
  }

  async getAll(): Promise<ConversationRecord[]> {
    // 实现获取逻辑
  }

  // 实现其他必需方法...
}

配置 MCP 客户端

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "recap": {
      "command": "node",
      "args": ["/path/to/recap/dist/index.js"]
    }
  }
}

HTTP 模式配置

{
  "mcpServers": {
    "recap-http": {
      "url": "http://localhost:3001/mcp",
      "transport": "streamable-http"
    }
  }
}

注意： 不同的 MCP 客户端可能对 HTTP 传输的支持有所不同。请查阅您使用的客户端文档以了解正确的配置格式。

技术栈

• Node.js - 运行时环境
• TypeScript - 类型安全的 JavaScript
• Express - Web 框架
• @modelcontextprotocol/sdk - MCP 协议 SDK
• Zod - 运行时类型验证和架构定义
• zod-to-json-schema - Zod 架构转换为 JSON Schema
• CORS - 跨域资源共享支持
• File System - 基于文件系统的本地存储
• pnpm - 包管理器

许可证

ISC

贡献

欢迎提交 Issues 和 Pull Requests！

更新日志

v1.0.0

• 初始版本
• 支持基本的 MCP 协议
• 包含对话记录工具 (conversation_recorder)
• 支持 stdio 和 HTTP 传输模式
• 基于文件系统的本地存储
• 支持对话标签、分类和搜索功能
• 提供对话统计和查询功能
• 包含调试脚本和测试工具