内容
# Memories.ai MCP 服务器
一种类型安全的模型上下文协议（MCP）服务器，使 AI 代理能够与 [Memories.ai](https://memories.ai) API 交互，提供全面的视频上传、搜索、聊天和管理功能，用于 AI 应用。
## 概述
该 MCP 服务器通过模块化、类型安全的架构，将 AI 代理与 Memories.ai 平台连接起来。它通过标准化的 MCP 接口提供与文件或 URL 的视频上传、语义搜索、AI 支持的视频聊天和全面的视频库管理功能的无缝集成。
## 功能
- 🎥 **视频上传** - 从本地文件或 URL 上传视频，检测 MIME 类型
- 🔍 **语义搜索** - 使用多种搜索类型（按视频、按音频、按剪辑）的高级语义搜索
- 💬 **AI 视频聊天** - 关于视频内容的流式对话，带有会话管理
- 📊 **视频管理** - 列出、删除和检查视频状态，支持分页和过滤
- 🔌 **MCP 兼容** - 完全符合 MCP 规范，包括工具、资源和提示
- 🔐 **安全认证** - 灵活的 API 密钥认证（环境变量或查询参数）
- ⚡ **类型安全架构** - 使用 TypeScript、Zod 验证和 better-fetch 构建
- 🚀 **流式响应** - 用于聊天功能的实时服务器发送事件
- 🎯 **智能提示** - 用于视频分析工作流的预构建提示模板
## 先决条件
- **Node.js 18+** 或 **Bun 运行时**（推荐）
- **TypeScript 4.5+** 用于开发
- **Memories.ai API 密钥**（[在此处获取](https://memories.ai/app/login)）
- **Claude Code** 或另一个 MCP 兼容客户端
## 安装
### 快速入门
```bash
# 克隆仓库
git clone https://github.com/yourusername/memories-ai-mcp.git
cd memcp
# 安装依赖（推荐 Bun）
bun install
# 构建项目
bun run build
```
### 环境设置
创建 `.env` 文件：
```env
# 从 https://memories.ai/app/login 获取您的 API 密钥（API 设置页面）
MEMORIES_API_KEY=您的_memories_ai_api_key
# 可选：覆盖默认 API 基本 URL
# MEMORIES_API_BASE_URL=https://api.memories.ai
# 可选：设置调试日志级别
# LOG_LEVEL=info
```
### API 密钥配置
API 密钥可以通过两种方式提供：
1. **环境变量（推荐）**：在 `.env` 文件中设置 `MEMORIES_API_KEY`
2. **每个工具参数**：在单个工具调用中包含 `api_key` 作为可选参数
每个工具参数优先于环境变量，允许多用户场景的灵活处理。
## 用法
### 添加到 Claude Code
将 MCP 服务器添加到 Claude Code：
```bash
claude mcp add memories-ai --env MEMORIES_API_KEY=您的密钥 -- node /path/to/memories-ai-mcp/dist/index.js
```
或使用已构建的可执行文件：
```bash
claude mcp add memories-ai --env MEMORIES_API_KEY=您的密钥 -- /path/to/memories-ai-mcp/dist/index.js
```
### 可用的 MCP 工具
服务器为 AI 代理公开了 8 个全面的工具：
#### `upload-video-file`
从本地存储上传视频文件到 Memories.ai
```json
{
"file_path": "/path/to/video.mp4",
"unique_id": "user123",
"callback": "https://callback.url/webhook",
"video_name": "我的视频"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `upload-video-url`
从 URL 上传视频到 Memories.ai
```json
{
"url": "https://example.com/video.mp4",
"unique_id": "user123",
"callback": "https://callback.url/webhook",
"video_name": "我的视频"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `search-videos`
使用自然语言搜索上传的视频，并具有高级选项
```json
{
"query": "人们谈论 AI",
"unique_id": "user123",
"search_type": "BY_VIDEO",
"folder_id": -1
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `chat-with-videos`
关于一个或多个视频的流式 AI 对话
```json
{
"video_nos": ["vid123", "vid456"],
"prompt": "总结主要讨论点",
"unique_id": "user123",
"session_id": "session123"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `list-videos`
获取上传视频的分页列表，并具有过滤选项
```json
{
"unique_id": "user123",
"page": 1,
"size": 20,
"video_name": "可选筛选",
"video_no": "可选 ID 筛选",
"status": "PARSE"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `delete-videos`
从 Memories.ai 删除一个或多个视频
```json
{
"video_nos": ["vid123", "vid456"],
"unique_id": "user123"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
#### `check-video-status`
检查上传视频的处理状态
```json
{
"video_nos": ["vid123"],
"unique_id": "user123"
}
```
*注意：API 密钥可以作为可选的 `api_key` 参数或通过环境变量提供*
### MCP 资源
#### `memories://docs`
全面的 API 文档和平台功能
- 完整的端点参考
- 身份验证方法
- 速率限制和最佳实践
- 故障排除指南
#### `memories://video/{videoNo}`
关于特定视频的详细信息
- 视频元数据和状态
- 处理信息
- 使用示例
### MCP 提示
#### `analyze-video-content`
为视频内容分析生成专用提示
- **分析类型**：摘要、情感、对象、活动、转录、 技术、教育
- **详细级别**：简要、详细、全面
- **关注区域**：自定义关注特定方面
- **上下文指令**：每种分析类型的专用指导
#### `build-search-query`
智能搜索查询构造辅助
- **搜索方法**：视觉、音频、综合内容定位
- **特定级别**：广泛、具体、精确查询范围
- **上下文集成**：结合其他搜索参数
- **查询优化**：平衡精度和召回策略
#### `video-workflow-helper`
常见任务的逐步工作流指导
- **工作流类型**：上传、搜索、分析、管理、集成、故障排除
- **经验级别**：初学者、中级、高级指导
- **最佳实践**：可行的建议和避免陷阱
- **工具集成**：特定的 MCP 工具使用建议
## 开发
### 项目结构
```
memcp/
├── src/
│ ├── index.ts # 主要的 MCP 服务器入口点
│ ├── types/
│ │ └── memories.ts # TypeScript 类型和 Zod 模式
│ ├── clients/
│ │ └── memories.ts # 类型安全的 Memories.ai API 客户端
│ ├── tools/
│ │ ├── upload.ts # 视频上传工具
│ │ ├── search.ts # 视频搜索工具
│ │ ├── chat.ts # 视频聊天工具
│ │ └── utils.ts # 视频管理工具
│ ├── resources/
│ │ └── index.ts # MCP 资源（文档，视频详情）
│ ├── prompts/
│ │ └── index.ts # MCP 提示，用于工作流
│ └── utils/
│ ├── api-key.ts # API 密钥管理
│ └── mime-types.ts # MIME 类型实用程序
├── dist/ # 已构建的 JavaScript 文件
├── memories-ai-docs/ # 本地 API 文档
├── package.json # 项目配置
├── tsdown.config.ts # 构建配置
├── tsconfig.json # TypeScript 配置
├── biome.jsonc # 代码格式化配置
└── .env # 环境变量
```
### 可用的脚本
- `bun run dev` - 使用监视模式启动开发服务器
- `bun run build` - 使用 tsdown 构建项目
- `bun run typecheck` - 运行 TypeScript 类型检查
- `bun run check` - 运行 Biome 校验和格式化
- `bun run check:fix` - 运行 Biome 并自动修复
- `bun run start` - 启动已构建的服务器
### 构建
```bash
bun run build
```
这会创建一个具有正确 shebang 的可执行 `dist/index.js` 文件，以便直接执行。
## API 参考
### Memories.ai API 集成
服务器与 Memories.ai API v1.2 集成：
- **基本 URL**：`https://api.memories.ai`
- **身份验证**：授权头中的 API 密钥
- **支持的格式**：h264, h265, vp9, hevc
- **语言**：英语（提示和聊天）
### 错误处理
服务器返回标准化的 MCP 错误响应：
- 身份验证失败
- API 速率限制
- 无效参数
- 网络错误
## 示例
### 基本视频上传
```typescript
// AI 代理可以自动使用此工具
await upload_video_url({
url: "https://example.com/presentation.mp4",
unique_id: "user123",
video_name: "团队演示"
});
```
### 语义视频搜索
```typescript
// 搜索视频中的特定内容
const results = await search_videos({
query: "讨论季度目标",
unique_id: "user123",
search_type: "BY_VIDEO"
});
```
### AI 视频聊天
```typescript
// 聊天关于视频内容
const response = await chat_with_videos({
video_nos: ["vid123"],
prompt: "有哪些主要行动项？",
unique_id: "user123"
});
```
## 故障排除
### 常见问题
**MCP 服务器无法连接**：
- 确保服务器使用 `bun run build` 成功构建
- 检查 API 密钥是否正确设置在环境变量中
- 验证 Node.js 版本兼容性
**API 身份验证错误**：
- 验证您的 Memories.ai API 密钥是否有效
- 检查密钥是否正确设置在 MCP 配置中
**视频上传失败**：
- 确保视频 URL 是公开可访问的
- 检查支持的视频格式（h264, h265, vp9, hevc）
- 验证速率限制是否未超过
### 调试模式
使用调试日志运行：
```bash
claude --debug
```
在以下位置检查 MCP 服务器日志：
```
/Users/[username]/Library/Caches/claude-cli-nodejs/[project-path]/
```
## 依赖项
### 运行时依赖项
- `@modelcontextprotocol/sdk` - 用于 TypeScript 的 MCP SDK
- `@better-fetch/fetch` - 类型安全的 HTTP 客户端，带有模式验证
- `zod` - 运行时类型验证和模式解析
### 开发依赖项
- `@biomejs/biome` - 快速格式化和校验
- `tsdown` - 现代 TypeScript 打包器
- `typescript` - TypeScript 编译器
## 架构
### 类型安全
- **全面的类型**：完整的 TypeScript 覆盖，带有 Zod 运行时验证
- **基于模式的客户端**：better-fetch 集成，带有预定义的 API 模式
- **请求/响应验证**：所有 API 交互的自动验证
### 错误处理
- **优雅降级**：全面的错误消息，带有故障排除指导
- **重试逻辑**：暂存故障的指数退避
- **验证错误**：清晰的无效参数反馈
### 性能
- **流媒体支持**：用于实时聊天响应的服务器发送事件
- **高效上传**：优化的文件处理，带有 MIME 类型检测
- **连接池**：可重用的 HTTP 连接，带有超时管理
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 贡献
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
## 了解更多
- [Memories.ai API 文档](https://memories.ai/api)
- [模型上下文协议文档](https://modelcontextprotocol.io/)
- [Claude Code MCP 指南](https://docs.anthropic.com/en/docs/claude-code/mcp)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
