AI导哈

动态MCP代理服务器

一款智能MCP代理服务器，根据项目上下文懒加载相关MCP工具服务器，保持AI工具数量在推荐限制内，适用于高自治环境中的代理工具集动态管理。

  • by HappyMonkeyAI
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 SPhillips1337/DynamicMCPProxy

使用说明

动态MCP代理

一个智能MCP代理服务器，根据您的项目上下文延迟加载相关的MCP工具服务器，将AI工具计数保持在推荐的限制范围内（对于Google Antigravity，≤50个工具）。专为需要开发自己的工具集的高自主性环境而设计。

部分 反重力剂提示协议 生态系统。

这个项目是一个可行的、与客户无关的解决方案 人类学/克劳德编码#7336-- 功能请求：MCP服务器和工具的延迟加载. 看 相关工作 在......下面

运作原理

IDE connects → proxy exposes proxy_* tools + MCP Resources + Prompts
AI calls proxy_handshake({ tech_stack, task_description })
  → Matcher scores catalogue entries
  → Top-5 servers activated (lazily mounted as stdio subprocesses or SSE)
  → tools/list now includes those servers' tools
  → Budget cap (50 tools) enforced via LRU eviction

快速开始

先决条件

目录服务器通过运行 npx （Node.js）和 uvx （紫外线）。这些必须在IDE生成代理时使用的PATH上。在MCP配置中明确添加它们 env 块（见下文）。找到你的路 type npx 和 type uvx.

安装

使用强化安装程序进行安装（克隆或就地安装）：

curl -fsSL https://raw.githubusercontent.com/SPhillips1337/DynamicMCPProxy/main/install.sh -o install.sh
chmod +x install.sh
./install.sh --dir "$HOME/DynamicMCPProxy"

如果您已经克隆了存储库，请从项目根目录运行安装程序：

./install.sh

安装程序在更新之前验证现有的目标目录是否是此存储库，检查所需的工具(git 和 uv)，运行 uv sync，并创建 proxy_config.json 从 proxy_config.json.example 必要时。要检查首次安装，请在执行脚本之前下载并查看脚本；除非您信任源代码，否则请避免将远程脚本直接管道传输到shell中。

手动安装仍然存在：

uv sync

配置

复制示例配置：

cp proxy_config.json.example proxy_config.json

设置您的环境和私人目录：

cp .env.example .env          # fill in your API keys
# user.catalogue.json is auto-created or copy from your IDE's mcp_config.json

添加到您的IDE（反重力/开放代码/克劳德桌面）

{
  "mcpServers": {
    "dynamic-proxy": {
      "command": "uv",
      "args": [
        "run",
        "--quiet",
        "--project",
        "/path/to/dynamic-mcp-proxy-server",
        "python", "-m", "src.proxy_server"
      ],
      "env": {
        "PATH": "/home/user/.nvm/versions/node/v20.18.1/bin:/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

调整 PATH 以匹配您的系统(type npx 和 type uvx 显示正确的目录）。

proxy_*工具

工具 说明
proxy_handshake(tech_stack, task_description, ...) 上下文握手——激活相关服务器
proxy_list_active_servers() 当前安装的服务器+工具数量
proxy_list_available_servers(filter_tag?) 浏览目录
proxy_activate_server(name, eager?) 装载服务器（默认情况下延迟）
proxy_activate_from_spec(name, url, type?, lean?) 从OpenAPI/GraphQL生成并挂载服务器（lean=True使用LAP来实现更小的规格）
proxy_deactivate_server(name) 释放工具预算
proxy_add_custom_proxy(name, url, tags, runtime) 添加临时服务器（仅限SSE/HTTP）
proxy_list_tools(server_name?) 列出所有安装工具的确切名称
proxy_inspect_registry() 诊断：当前工具注册表的完整转储
proxy_get_metrics() 实时内存/CPU/正常运行时间指标
proxy_get_usage() 服务器使用率对自我进化排名很重要
proxy_reset_usage(server?) 重置使用统计数据（用于测试/重新基线化）

MCP资源

URI 描述
mcp://proxy/info 静态元数据（版本、功能）
mcp://proxy/health 实时健康状况（正常运行时间、内存、活动工具）
mcp://proxy/servers 完整的服务器资源清册（活动+可用）

MCP发现表面

MCP方法 AI看到了什么
tools/list 最小 proxy_* 管理工具
resources/list + resources/read 实时健康状况、代理信息、服务器清单
prompts/list suggest_tools_for_context 引导式工作流程

目录

catalogue.json --49个公共MCP服务器（GitHub、Docker、Postgres、Slack、Stripe等）。

user.catalogue.json --您的私人覆盖（gitignored）。在此处添加个人服务器——本地路径、私有API、自定义工具。同名条目会覆盖公共目录。

[
  {
    "name": "my-server",
    "description": "My private MCP server",
    "command": "python /path/to/server.py",
    "tags": ["custom"],
    "tech_stack": ["any"],
    "runtime": "stdio",
    "env_vars": ["MY_API_KEY"],
    "pick": ["id", "status"],
    "token_budget": 500
  }
]

响应转向

通过在服务器响应到达LLM之前对其进行整形来优化AI上下文的使用。适用于任何服务器（stdio、SSE、REST）：

  • pick：要保留的点标记路径数组（所有其他路径均已删除）。
  • omit：要删除的路径数组。
  • template：Python风格的格式字符串（例如。， "{id}: {content}")将复杂的JSON转换为可读文本。
  • token_budget：硬字符上限（大约标记*4），以防止上下文泛滥。

REST网桥支持（通过40mcp）

代理支持 runtime: "rest"，允许它作为任何OpenAPI或GraphQL API的桥梁。

  1. 自动生成：使用 proxy_activate_from_spec(name, url) 在中生成服务器配置 ./configs/ 并立即安装。
  2. 手动设定：添加一个条目 "runtime": "rest" 和 "config_path": "configs/mysvc.json"。代理使用 40mcp 引擎将MCP工具调用映射到REST/GraphQL请求。

环境变量

.env （gitignored）在启动时自动加载。复制 .env.example 开始：

cp .env.example .env

按键跟随 env_vars 每个目录条目中的字段。真实环境变量中的值始终优先于 .env 文件。

配置

proxy_config.json （gitignored，使用安全默认值自动生成）：

{
  "tool_budget": 50,
  "auth_enabled": false,
  "guardrails_enabled": true,
  "rate_limit_rpm": 120,
  "catalogue_path": "catalogue.json",
  "audit_log_path": "audit.log",
  "receipts_enabled": true,
  "otel_enabled": false,
  "otel_service_name": "dynamic-mcp-proxy",
  "otel_exporter_otlp_endpoint": null,
  "otel_capture_content": false
}

关键设置：

  • tool_budget --一次暴露的最大工具数（默认值50，符合反重力限制）
  • auth_enabled -用于生产的JWT RS256+HMAC API密钥验证
  • guardrails_enabled --快速注射扫描+结果大小上限
  • receipts_enabled --将JSONL收据写入 audit_log_path 随着 run_id, span_id、调用者、状态、延迟、服务器/工具名称和隐私安全参数摘要
  • otel_enabled --在以下情况下，可以选择将接收事件镜像到OpenTetry中 opentelemetry-* 软件包已安装；JSONL收据在没有这些可选包的情况下继续工作
  • otel_capture_content --默认为 false；默认情况下，不捕获跟踪中的原始提示、客户内容、API密钥或工具有效负载

收据和可追溯性

DynamicMCPProxy是收集代理收据的正确位置，因为每次服务器激活和子MCP工具调用都会通过它。默认情况下，收据在 audit.log 专为安全第一调试而设计：

  • 每条记录都包括 run_id 和 span_id；相关操作可以传递父跨度（如果可用）。
  • HMAC/JWT调用者由身份验证类型标识，而不是由秘密值标识。例如，sidecar HMAC调用记录 service:hmac.
  • 工具参数概括为密钥、类型、长度和SHA-256指纹。未记录原始字符串、嵌套有效负载、密码、令牌、cookie和API密钥。
  • OpenTetry导出是可选的，依赖关系是可选的。如果在未安装OTel包的情况下启用，代理会向stderr记录一个警告，并继续使用JSONL收据。

JSONL记录形状示例：

{
  "ts": "2026-07-04T12:00:00+00:00",
  "event_type": "mcp.tool.call",
  "run_id": "run_...",
  "span_id": "...",
  "tool": "github_search",
  "caller": "service:hmac",
  "outcome": "ok",
  "latency_ms": 42.1,
  "server": "github",
  "argument_keys": ["query"],
  "redacted_args": {
    "query": {"type": "str", "length": 12, "sha256": "..."}
  }
}

安全

当 auth_enabled = true:

  • JWT（RS256）——套装 jwt_public_key_path 到您的RSA公钥PEM
  • HMAC API密钥集 hmac_api_key （通过 X-API-Key 头球
  • 护栏——对所有工具描述进行8次快速注射模式检查
  • 审计日志/收据——记录到的每个工具调用 audit.log （JSON行）具有隐私安全的参数指纹，而不是原始秘密或有效载荷
  • 速率限制——每个呼叫者可配置的RPM

热插拔插件

将任何可执行的MCP服务器脚本放入 ./plugins/。代理通过监视器检测到它并实时注册——不需要重新启动。

自主工具和热插拔

这个代理的真正力量在于 运行时突变与静态MCP配置不同，此代理允许代理随着任务的进展“进化”其工具箱：

  1. 即时激活：运行数小时的A2A（代理到代理）工作流可以激活 sequential-thinking 只有当碰到复杂的逻辑门时，才将其换成 docker 或 terraform 在执行阶段。
  2. 自主Bootstrap：代理可以研究新工具，通过以下方式配置其环境 proxy_add_custom_proxy，并立即开始使用，无需人工干预。
  3. 自我修正：如果缺少工具，代理可以编写一个新的MCP服务器 ./plugins/ 代理将立即对其进行热插拔。
  4. 代币可持续性：通过保持活动工具集的精简（通过LRU驱逐），长时间运行的代理可以避免上下文窗口饱和，并保持对任务的峰值关注。

更新公共目录

uv run python scripts/sync_catalogue.py

运行测试

uv run pytest tests/ -v

可选HTTP端点

默认情况下禁用。启用 ENABLE_HTTP_SIDECAR=1:

curl -X POST http://localhost:8765/handshake \
  -H "Content-Type: application/json" \
  -d '{"tech_stack": ["python", "fastapi"], "task_description": "Building a REST API"}'

长时程记忆

该项目使用反重力LTM协议。回购在 docs/memories/.每个开发人员的上下文都存在于 .antigravity/memories/ （忽略）：

  • patterns_and_lessons.md --解决了问题，失败了
  • codebase_insights/ --模块级隐藏知识
  • architectural_decisions/ --设计权衡和基本原理

按照以下步骤启动本地LTM BOOTSTRAP.md 来自协议仓库。看 AGENTS.md 对于完整的代理协议。

存储库文档

  • README.md --用户概述和入门
  • CONTEXT.md --简明操作手册（堆栈、规则、决策、指导）
  • AGENTS.md --代理行为、工作流规则和LTM协议（HERMES等效协议）
  • docs/memories/ --活记忆：模式、见解、架构决策
  • research/ --外部参考、比较和注释（非事实来源）

相关工作和问题背景

人类学/克劳德编码#7336 记录了一个真正的问题：在会话启动时加载所有MCP服务器可能会消耗 54%的可用上下文窗口 （约108k的200k令牌）在发送单个消息之前。已经提出或建立了几种方法：

项目 方法 限制
machjessmoto/claude延迟加载 离线注册表生成器——从MCP配置中生成轻量级令牌索引 无运行时注入；明确列出 “运行时自动延迟加载” 需要Claude Code支持
街区镇/mcp门户 用3-4个通用工具替换所有工具 gw(service, tool, args) 垫片工具；调用时分派 硬编码，要求每栈分叉和编辑；AI失去了完整的工具类型安全性和发现能力
这个项目 智能代理，通过以下方式仅激活与当前项目上下文相关的服务器 proxy_handshake()，通过LRU驱逐强制执行工具预算，并且在运行时完全动态 与 任何 今天的MCP客户端--不需要更改IDE

为什么MCP层是解决这个问题的合适位置

  1. 客户不可知 --代理透明地处理任何MCP客户端（Claude Code、Windsurf、Antigravity、opencode、Claude Desktop…）的延迟加载，而不仅仅是一个IDE。
  2. proxy_handshake() 已经从问题中交付了“之后”的用户体验 --功能请求的理想示例显示 > Auto-loading: context7, magic [+3.5k tokens] 在检测到用户输入中的关键字之后。这正是 proxy_handshake({ tech_stack, task_description }) 今天做。
  3. 无需叉子 --将服务器添加到 catalogue.json 或 user.catalogue.json；匹配器和预算执行是自动的。

灵感

相关 MCP