Recallbricks MCP Simple

RecallBricks MCP服务器v2.0-生产就绪

用于RecallBricks内存管理的企业级模型上下文协议（MCP）服务器。

以可靠性、可观察性和用户体验为重。具有自动重试、断路器、请求缓存、优雅降级和全面的健康监测功能。

______________________________________________________________________

特性

核心可靠性

• 伴随抖动的指数级回退 -智能重试策略可防止雷鸣般的羊群问题
• 断路器型式 -服务降级时自动停止请求
• 请求超时保护 -防止挂起请求（默认30秒）
• 在标头支持后重试 -尊重服务器速率限制信号
• 请求重复数据删除 -防止重复的同时请求

故障弱化

• 内存缓存 -在API不可用时提供缓存结果
• 回退机制 -在部分停机期间继续运行
• 智能错误恢复 -服务恢复时自动修复

可观测性

• 结构化日志记录 -JSON格式的监控指标
• 健康检查系统 -定期健康验证（间隔5分钟）
• 请求度量 -跟踪尝试次数、持续时间、成功率
• 断路器统计数据 -实时服务健康状况可见性

开发者体验

• 完整TypeScript -类型安全API响应和错误
• 输入验证 -全面的参数验证
• 丰富的错误消息 -带有HTTP状态代码的详细错误上下文
• 基于环境的配置 -通过env变量轻松配置

______________________________________________________________________

快速开始

1.安装

npm install
npm run build

2.配置

创建一个 .env 文件（参见 .env.example):

RECALLBRICKS_API_URL=https://your-api-url.com
RECALLBRICKS_API_KEY=your_api_key_here

3.跑步

node dist/index.js

______________________________________________________________________

配置

所有设置都可以通过环境变量进行配置：

API配置

可靠性设置

断路器

缓存

监控

验证

______________________________________________________________________

可用工具

1. create_memory

将新内存保存到具有自动重试和断路器保护的RecallBricks。

参数：

• text （字符串，必填）：要保存的内存内容（最多10000个字符）

例子：

{
  "text": "Claude Code is an amazing development tool"
}

答复：

✅ Memory saved successfully!

ID: mem_abc123
Created: 2025-01-15T10:30:00Z
Length: 45 characters

______________________________________________________________________

2. query_memories

使用缓存和回退支持搜索和检索内存。

参数：

• query （字符串，必填）：搜索查询
• limit （数字，可选）：最大结果（1-100，默认值：5）

例子：

{
  "query": "development tools",
  "limit": 10
}

答复：

📚 Found 3 memories (total available: 15):

1. [mem_abc123] Claude Code is an amazing development tool
   Created: 2025-01-15T10:30:00Z

2. [mem_def456] VSCode extensions improve productivity...
   Created: 2025-01-14T09:15:00Z

______________________________________________________________________

3. get_health

获取MCP服务器的当前运行状况和指标。

参数： 无

答复：

{
  "status": "healthy",
  "circuitBreaker": {
    "state": "CLOSED",
    "failures": 0,
    "lastFailureTime": 0,
    "successCount": 0
  },
  "cache": {
    "size": 12,
    "ttl": 3600000
  },
  "config": {
    "maxRetries": 3,
    "requestTimeout": 30000,
    "apiUrl": "https://..."
  }
}

______________________________________________________________________

建筑

请求流

User Request
    ↓
Input Validation
    ↓
Circuit Breaker Check
    ↓
Request Deduplication
    ↓
Fetch with Retry (exponential backoff + jitter)
    ↓
Response Caching
    ↓
Success / Fallback to Cache

断路器状态

1. 关闭 （正常）

- 所有请求都通过 - 跟踪故障

1. 打开 （服务中断）

- 请求立即失败 - 未调用API - 超时后，转换到HALF_OPEN

1. 半开 （测试恢复）

- 允许的请求有限 - 如果2成功→ 关闭 - 如果有任何失败→ OPEN

错误处理

所有错误包括：

• 状态代码
• 描述的消息
• 请求上下文（URL，尝试次数）
• 原始错误详细信息

示例错误：

❌ Error: Failed to create memory: Service unavailable (HTTP 503)

______________________________________________________________________

度量与记录

所有日志都是JSON格式，便于解析：

请求度量

{
  "timestamp": "2025-01-15T10:30:00.000Z",
  "type": "http_request",
  "url": "https://api.com/memories",
  "method": "POST",
  "attempts": 2,
  "totalDuration": 1523,
  "success": true,
  "statusCode": 200
}

健康检查

{
  "timestamp": "2025-01-15T10:35:00.000Z",
  "type": "health_check",
  "healthy": true,
  "statusCode": 200,
  "circuitBreaker": {
    "state": "CLOSED",
    "failures": 0
  }
}

缓存请求

{
  "url": "...",
  "cached": true,
  "success": true
}

______________________________________________________________________

生产部署

推荐设置

高流量生产：

RECALLBRICKS_MAX_RETRIES=5
CIRCUIT_BREAKER_THRESHOLD=10
CACHE_TTL=7200000  # 2 hours
ENABLE_METRICS=true

低延迟要求：

RECALLBRICKS_TIMEOUT=10000  # 10 seconds
RECALLBRICKS_BASE_DELAY=500
RECALLBRICKS_MAX_RETRIES=2

发展：

ENABLE_METRICS=false
ENABLE_HEALTH_CHECKS=false
RECALLBRICKS_MAX_RETRIES=1

监控

监控这些指标：

• 断路器状态转换
• 请求成功率
• 平均重试次数
• 缓存命中率
• 响应时间

告警

为以下对象设置警报：

• 断路器打开状态
• 高重试率（>50%的请求）
• 错误率上升
• 停机期间缓存丢失

______________________________________________________________________

故障排除

断路器卡住打开

症状： 所有请求均以“断路器打开”失败

解决方案：

1. 检查API运行状况： get_health 工具
2. 验证API_URL和API_KEY
3. 等待断路器超时（默认60秒）
4. 检查日志中是否存在潜在的API错误

超时错误

症状： “30000ms后请求超时”

解决方案：

1. 增加超时时间： RECALLBRICKS_TIMEOUT=60000
2. 检查网络连接
3. 验证API性能

缓存不工作

症状： API中断期间无回退

解决方案：

1. 确保查询完全相同（缓存键基于URL）
2. 检查缓存TTL是否未过期
3. 验证是否缓存了至少一个成功的请求

内存使用率高

症状： 服务器内存随时间增长

解决方案：

1. 减少缓存TTL
2. 限制并发请求
3. 监控缓存大小 get_health

______________________________________________________________________

发展

建筑

npm run build

观看模式

npm run watch

本地测试

# Terminal 1
npm run build && node dist/index.js

# Terminal 2
# Use with Claude Desktop or MCP client

______________________________________________________________________

更新日志

v2.0.0-生产就绪

• 增加了断路器模式
• 已实施请求重复数据删除
• 通过缓存添加了优雅的降级
• 增强重试逻辑，支持重试后
• 添加了全面的输入验证
• 实施结构化指标记录
• 新增健康检查系统
• 完全TypeScript类型安全
• 请求超时保护
• 更好的带有上下文的错误消息
• 基于环境的配置

v1.0.0-初始版本

• 基本重试逻辑
• 简单的axios集成

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

支持

对于问题、功能请求或疑问：

• GitHub问题：\[你的仓库/问题\]
• 文档：此自述文件
• 健康检查：使用 get_health 工具

______________________________________________________________________

内置❤️ 可靠性和用户体验。