使用说明

Vercel MCP存储器

部署在Vercel上的自定义模型上下文协议（MCP）内存服务器，其语义搜索由OpenAI嵌入和PostgreSQL pgvector提供支持。

✨ 特性

🧠 语义搜索 -通过意义而不仅仅是关键字来寻找记忆
🔐 安全API -用于生产的可选API密钥身份验证
☁️ 云托管 -部署在Vercel边缘功能上（零基础设施）
🔄 跨设备同步 -使用Claude从任何设备访问您的内存
🚀 OpenAI嵌入 -使用文本嵌入3-small模型
🗄️ PostgreSQL+pgvector -高效的向量相似度搜索
✅ 输入验证 -用于稳健数据验证的Zod模式
📝 结构化日志记录 -生产就绪错误跟踪
🌍 多语言 -支持俄语、英语等
🤖 Claude代码集成 -通过GitHub Actions实现自动公关审核和人工智能助手

🏗️ 建筑

Claude Desktop → HTTPS/JSON-RPC → Vercel Edge Function → Postgres (pgvector)
                                         ↓
                                   OpenAI Embeddings API

📋 先决条件

Node.js 20.x
Vercel帐户（免费版有效）
OpenAI API密钥（用于嵌入，约10美元/1M代币）
带pgvector扩展的PostgreSQL数据库（Vercel Postgres或Neon）

🚀 快速开始

1.安装依赖项

cd vercel-mcp-memory
npm install

2.设置Vercel Postgres

# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Link project
vercel link

# Create Postgres database (via Vercel Dashboard)
# 1. Go to https://vercel.com/dashboard
# 2. Navigate to Storage → Create Database → Postgres
# 3. Name: mcp-memory-db
# 4. Region: Select closest to you

3.配置环境变量

创建 .env.local 文件：

# Required: OpenAI API key for embeddings
OPENAI_API_KEY=sk-...

# Required: PostgreSQL connection (auto-configured by Vercel)
POSTGRES_URL=postgresql://...

# Optional: API keys for authentication (comma-separated)
# Leave empty for development without auth
MCP_API_KEYS=your-secret-key-1,your-secret-key-2

生成安全的API密钥：

# Generate a secure API key
openssl rand -base64 32

4.运行数据库迁移

应用扩展名为pgvector的SQL模式：

# Option 1: Via Vercel Dashboard
# 1. Go to Storage → mcp-memory-db → SQL Editor
# 2. Copy contents of migrations/001_init.sql
# 3. Execute

# Option 2: Via psql (if you have local connection)
psql $POSTGRES_URL < migrations/001_init.sql

5.部署到Vercel

vercel --prod

您的MCP服务器将在以下网址提供： https://your-project.vercel.app

6.配置克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 ~/.config/claude-desktop/claude_desktop_config.json （Linux）：

带身份验证（建议用于生产）：

{
  "mcpServers": {
    "vercel-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp/sse"
      ],
      "env": {
        "MCP_API_KEY": "your-secret-key-here"
      }
    }
  }
}

无身份验证（仅用于开发）：

{
  "mcpServers": {
    "vercel-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp/sse"
      ]
    }
  }
}

重新启动克劳德桌面。

🧪 测试

健康检查

curl https://your-project.vercel.app/api/health

应返回：

{
  "status": "healthy",
  "service": "vercel-mcp-memory",
  "database": {
    "connected": true
  }
}

使用身份验证测试MCP端点

curl -X POST https://your-project.vercel.app/api/mcp/sse \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

克劳德测试

User: Remember: I prefer Python for backend development
Claude: [Uses add_memory tool]

User: What programming languages do I prefer?
Claude: [Uses search_memory tool and finds "Python"]

📊 MCP工具

`add_memory`

使用语义嵌入存储新内存。

{
  content: string,      // Required (1-10000 chars)
  category?: string,    // Optional (max 100 chars)
  metadata?: object     // Optional custom key-value pairs
}

`search_memory`

跨记忆的语义搜索。

{
  query: string,        // Required: natural language query (1-1000 chars)
  category?: string,    // Filter by category
  limit?: number,       // Max results (default: 10, max: 50)
  threshold?: number    // Min similarity 0-1 (default: 0.5)
}

`list_memories`

按时间顺序列出所有记忆。

{
  category?: string,    // Filter by category
  limit?: number,       // Max results (default: 50, max: 100)
  offset?: number       // Pagination offset (default: 0)
}

`delete_memory`

按UUID删除特定内存。

{
  id: string           // UUID of memory (validated)
}

`memory_stats`

获取有关存储内存的统计信息。

{}  // No parameters

📁 项目结构

vercel-mcp-memory/
├── app/
│   ├── api/
│   │   ├── health/route.ts          # Health check endpoint
│   │   └── mcp/sse/route.ts         # MCP JSON-RPC endpoint
│   ├── layout.tsx                   # Next.js layout
│   └── page.tsx                     # Landing page
├── lib/
│   ├── auth.ts                      # API authentication
│   ├── db.ts                        # Postgres + pgvector queries
│   ├── embeddings.ts                # OpenAI embeddings client
│   ├── logger.ts                    # Structured logging
│   ├── mcp-handlers.ts              # Centralized tool handlers
│   ├── mcp-server.ts                # MCP SDK integration
│   ├── types.ts                     # TypeScript definitions
│   └── validation.ts                # Zod input validation
├── migrations/
│   └── 001_init.sql                 # Database schema
├── scripts/
│   ├── insert-test-data.ts          # Test data seeding
│   └── migrate-old-data.ts          # Legacy data migration
├── .env.example                     # Environment variables template
├── .eslintrc.json                   # ESLint configuration
├── .gitignore                       # Git ignore rules
├── SECURITY.md                      # Security guidelines
├── next.config.js                   # Next.js configuration
├── package.json                     # Dependencies
├── tsconfig.json                    # TypeScript configuration
└── vercel.json                      # Vercel deployment config

🔧 发展

# Run locally
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

# Migrate old data
npm run migrate

🔐 安全

看安全.md 安全最佳实践。

重要提示：

永不承诺 .env.local 或 .env.production 文件
定期旋转API键
启用 MCP_API_KEYS 生产中的身份验证
监控API使用情况以防止配额耗尽
审查安全.md 部署前

💰 成本估算

Vercel免费套餐（足够个人使用）：

✅ 功能：100GB小时/月
✅ Postgres：256 MB存储空间
✅ 带宽：100 GB

免费等级之后：

邮费：约0.20美元/GB/月
OpenAI嵌入：约0.10美元/1M代币（典型使用约0.02美元/月）
功能：约40美元/100 GB小时

预期成本：0-5美元/月，供适度个人使用。

🐛 故障排除

克劳德无法连接

检查运行状况端点： curl https://your-project.vercel.app/api/health
验证Vercel env和Claude配置中的API密钥匹配
检查Vercel部署： vercel ls
验证Claude配置路径是否正确
重新启动克劳德桌面

身份验证错误

验证 MCP_API_KEYS 在Vercel环境变量中设置
检查API密钥格式（没有额外的空格或换行符）
确保Claude配置包括 MCP_API_KEY 在env部分
先尝试不进行身份验证（删除 MCP_API_KEYS 来自Vercel env）

数据库错误

验证pgvector扩展是否已启用：

SELECT * FROM pg_extension WHERE extname = 'vector';

检查表存在：
```
\dt memories
```
在Vercel仪表板中查看连接日志→ 函数→ Logs

嵌入错误

验证是否设置了OpenAI API密钥： vercel env ls
检查API密钥是否有足够的信用
监控使用情况： https://platform.openai.com/usage

📖 资源

🤖 Claude代码集成

该存储库通过GitHub Actions使用Claude Code进行自动代码审查和人工智能协助。

自动PR审核

每个pull请求都会自动收到Claude的全面代码审查，重点是：

代码质量和最佳实践
潜在的漏洞和安全问题
性能考虑
测试覆盖率

交互式人工智能助手

提及 @claude 在任何问题或公关评论中寻求帮助：

@claude Please review the security implications of these auth changes.
@claude Help me fix the TypeScript errors in lib/db.ts.
@claude Update CLAUDE.md to reflect the new architecture.

有关详细的设置和故障排除，请参阅 .github/CLAUDE_CODE_SETUP.md.

📝 许可证

麻省理工学院

🤝 贡献

欢迎投稿！请阅读我们的贡献指南和行为准则第一。

快速步骤：

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

有关问题或支持，请参阅支持.md.

🙏 致谢

内置：

维塞尔 -托管和Postgres
Next.js -React框架
OpenAI -嵌入API
MCP-SDK -协议实施
pg向量 -向量相似性搜索

由以下材料制成❤️ 使用Vercel、Next.js和Claude Code