AI导哈

MCP智能代理

一个轻量级且可扩展的模型上下文协议（MCP）代理，位于LLM客户端和多个上游MCP服务器之间，提供透明路由、可配置缓存、延迟测量和请求审计等功能。

  • by ronzimer
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ronzimer/mcp-proxy

使用说明

MCP智能代理

轻便且可扩展 模型上下文协议（MCP）代理 它位于LLM客户端（例如Claude Desktop）和多个上游MCP服务器之间。

代理提供：

  • 透明MCP路由
  • 可配置缓存（精确和语义）
  • 延迟测量
  • 请求审核
  • 每服务器缓存策略

该系统旨在 通用的, 可扩展的，以及 服务器无关，允许集成多个MCP服务器（例如维基百科、天气API、实用工具），而无需特定于服务器的代理逻辑。

架构概述

该系统由两个主要部分组成。

代理核心(proxy_core.py)

中央TCP服务器负责：

  • 接受MCP请求
  • 管理缓存逻辑
  • 将请求转发到上游MCP服务器
  • 测量延迟
  • 记录请求和响应

代理核心充当系统的编排层。

代理端点(proxy_endpoint.py)

一个轻量级的客户端网桥，它：

  • 将MCP兼容客户端连接到代理核心
  • 转发MCP JSON-RPC消息
  • 标识上游服务器(server_id)
  • 提供 caller_id 用于请求跟踪

端点故意保持薄而透明。

请求流

  1. 客户端发送请求→ 代理终结点
  2. 端点转发请求→ 代理核心
  3. 代理核心：
  • 计算标准化缓存键
  • 应用配置的缓存策略
  • 检查缓存层
  • 返回HIT上的缓存响应
  • 否则，向上游转发请求
  1. 响应可选择缓存
  2. 记录请求元数据和延迟
  3. 响应返回给客户端

缓存模型

代理支持两层缓存架构。

精确缓存（SQLite）

精确缓存使用规范化参数存储确定性请求-响应映射。

存储的数据包括：

  • 缓存键
  • 过期时间戳
  • 响应有效载荷

该层提供精确的缓存命中率。

语义缓存（Qdrant）

语义缓存支持使用嵌入进行近似匹配。

这使得：

  • 语义相似的查询
  • 释义处理
  • 减少冗余上行呼叫

语义缓存是可选和可配置的。

TTL和缓存清理

两个缓存层都使用 基于TTL的过期.

系统执行以下操作：

  • 启动过期条目的清理
  • 定期垃圾收集
  • 保存有效的缓存条目

重新启动代理 不 自动清除缓存。

错误永远不会被缓存。

每服务器缓存策略

缓存行为可针对每个上游服务器进行配置。

支持的配置选项包括：

{
  "cache_enabled": true,
  "semantic_cache_enabled": true,
  "cache_ttl_s": 3600
}

这允许：

  • 完全缓存
  • 仅精确缓存
  • 无缓存

示例用例：

  • 天气API→ 更短的TTL
  • 维基百科→ 更长的TTL
  • 时间服务→ 缓存已禁用

延迟测量

代理记录了两个延迟指标。

latency_ms

代理处理总时间。

包括：

  • 缓存处理
  • 上游相互作用
  • 响应准备

upstream_latency_ms

等待上游MCP服务器所花费的时间。

缓存命中率对此指标没有贡献。

有意排除LLM推理延迟（例如克劳德生成时间）。

请求日志记录

SQLite维护一个仅可追加的请求日志，其中包含：

  • 服务器ID
  • 操作
  • 参数
  • 缓存状态
  • 延迟测量
  • 响应快照

这支持可观察性和离线分析。

配置

使用JSON配置文件配置代理。

例子：

{
  "db_path": "proxy_cache.sqlite",
  "listen": {
    "host": "0.0.0.0",
    "port": 8765
  },

  "defaults": {
    "cache_ttl_s": 3600,
    "timeouts_s": {
      "initialize": 60,
      "tools/list": 60,
      "tools/call": 180
    }
  },

  "servers": {
    "wiki": {
      "cmd": ["npx", "-y", "wikipedia-mcp-server"],
      "cache_enabled": true,
      "semantic_cache_enabled": true,
      "cache_ttl_s": 86400
    },

    "open-meteo": {
      "cmd": ["npx", "-y", "open-meteo-mcp-server"],
      "cache_enabled": true,
      "semantic_cache_enabled": true,
      "cache_ttl_s": 900
    },

    "time": {
      "cmd": ["uvx", "mcp-server-time"],
      "cache_enabled": false
    }
  }
}

运行代理

启动代理核心：

python3 proxy_core.py --config proxy_core_config.json

启动终结点：

python3 proxy_endpoint.py \
  --host 127.0.0.1 \
  --port 8765 \
  --server-id wiki \
  --caller-id local-client

可靠性

代理管理本地生成的MCP子流程，如果上游流程意外终止，可以自动重新启动。

项目目标

MCP智能代理探索了中介代理系统如何：

  • 减少冗余MCP流量
  • 提高响应能力
  • 支持智能缓存
  • 提供可观察性
  • 对客户端和上游服务器保持透明

相关 MCP