AI导哈

模型上下文协议服务器

企业级模型上下文协议服务器，提供自动重试、熔断机制、请求缓存、优雅降级和全面的健康监控功能，适用于高可靠性要求的应用场景。

  • by tkutsch77
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 tkutsch77/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配置

变量 默认值 描述
RECALLBRICKS_API_URL https://recallbricks-api-clean.onrender.com RecallBricks API端点（渲染）
RECALLBRICKS_API_KEY rbk_secret_2025_x7h2p9 API身份验证密钥

可靠性设置

变量 默认值 描述
RECALLBRICKS_MAX_RETRIES 3 每个请求的最大重试次数
RECALLBRICKS_BASE_DELAY 1000 指数退避的基延迟（毫秒）
RECALLBRICKS_TIMEOUT 30000 请求超时（毫秒）

断路器

变量 默认值 描述
CIRCUIT_BREAKER_THRESHOLD 5 断路前故障
CIRCUIT_BREAKER_TIMEOUT 60000 尝试关闭电路前的时间（毫秒）

缓存

变量 默认值 描述
CACHE_TTL 3600000 缓存生存时间（毫秒）（1小时）

监控

变量 默认值 描述
ENABLE_METRICS true 启用结构化日志记录
ENABLE_HEALTH_CHECKS true 启用定期健康检查
HEALTH_CHECK_INTERVAL 300000 健康检查间隔（毫秒）（5分钟）

验证

变量 默认值 描述
MAX_MEMORY_TEXT_LENGTH 10000 内存文本的最大字符数

可用工具

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. 关闭 （正常）

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

  2. 打开 （服务中断）

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

  3. 半开 （测试恢复）

    • 允许的请求有限
    • 如果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 工具

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

相关 MCP