MCP Hotswap Agent

MCPAI代理

提供方 Arj-01

AI代理 stdio · 本地进程 会话登录 社区 / 第三方
查看接入方式

一个生产级AI代理平台,支持运行时工具热插拔、LLM驱动的路由和全栈可观测性,新功能可通过添加Python文件实现无需重启或重新部署。

一句话选型结论

按资料字段整理

MCP Hotswap Agent 属于AI代理类 MCP 服务器,stdio · 本地进程,会话登录,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 15 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量15暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

AI代理平台Python本地部署工具热插拔LLM路由本地运行全栈可观测性

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
pip install -e ".[dev]"

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 15 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 15 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Hotswap Agent当前 15 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Arj-01上游标注的维护方 Arj-01
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

11.3 KB
来自项目仓库与上游目录的原文,未做删改

MCP热插拔多代理助手

通过模型上下文协议热插拔AI工具

一个生产级的人工智能代理平台,具有运行时工具热交换、LLM驱动的路由和全栈可观察性。通过删除Python文件可以添加新功能——无需重新启动代理,无需更改代码,也无需重新部署。

> 100%本地。 与Ollama一起完全在您的机器上运行。没有API密钥,没有云成本。


主要特点

  • 热插拔工具架构 --工具服务器开始处于休眠状态(AST已扫描,未运行)。它们在单个查询生命周期内按需加载、执行和使用后自动分离。
  • 动态工具发现 --路由器代理在启动时发现MCP服务器,并静态扫描休眠插件。新工具在通过REST API注册时立即出现。
  • LLM供电路由 --Ollama(llama3.2)从自然语言中选择正确的工具;支持并行多工具调度 asyncio.gather().
  • 自动参数校正 --当计数匹配时,将LLM生成的错误参数名称位置重新映射到架构正确的名称——零手动干预。
  • 完全可观察性 --6普罗米修斯指标,带有预构建的Grafana仪表板,涵盖P50/P95/P99延迟、工具调用率和错误率。
  • 对话记忆 --每个会话的聊天历史记录保存在Redis中,跨会话隔离。
  • 一个命令部署 — bash scripts/start.sh 显示全部7项服务,完全有线。

🏗 建筑

它是如何工作的:

  1. 用户通过Streamlit UI发送自然语言查询
  2. FastAPI路由器代理将查询+可用工具列表发送给Ollama
  3. LLM决定调用哪些工具(零、一或多)
  4. 休眠服务器按需热插拔——加载、执行,然后自动分离
  5. 工具通过MCP stdio会话并行执行
  6. 结果被合成为单个响应

技术栈

层 技术 目的
LLM Ollama+llama3.2 本地推理,零成本工具布线
代理 FastAPI+asyncio 具有并行工具执行的异步路由器代理
工具协议 MCP SDK(stdio传输) 标准化的工具发现和执行
热插拔引擎 AST扫描器+停止事件 休眠插件生命周期管理
注册表 Redis哈希+排序集 工具元数据、服务器映射、脚本路径
聊天历史 Redis列表(上限,50毫秒) 每会话会话持久性
UI Streamlit 聊天界面+服务器管理面板
监控 普罗米修斯+格拉法纳 6台仪器,P50/P95/P99延迟仪表板
编排 Docker Compose 7服务单命令部署

MCP工具服务器

服务器 工具 说明
计算器 (休眠-按需热插拔) calculate, percentage, split_bill, unit_convert, loan_emi 数学、转换、金融
网络研究 search_web, fetch_url, summarize_url DuckDuckGo搜索,页面抓取
笔记创建者 create_note, create_note_from_topic, list_notes, read_note 带YAML frontmatter的Markdown注释
油管 get_transcript, summarize_video, ask_about_video 转录提取、视频问答

4台服务器上共有14个工具。 计算器在需要之前保持休眠状态,证明零停机热插拔。


快速开始

先决条件

  • Docker桌面(分配4 GB+RAM)
  • Ollama与骆驼3.2拉```bash
    ollama pull llama3.2

### 跑```bash
git clone https://github.com/Arj-01/mcp-hotswap-agent.git
cd mcp-hotswap-agent
bash scripts/start.sh

这将启动所有7个服务(API、前端、Redis、Ollama、Prometheus、Grafana),并自动提取LLM模型。

服务 URL
聊天界面 http://localhost:8501
代理API http://localhost:8000/docs
格拉法纳 http://localhost:3000(管理员/管理员)
普罗米修斯 http://localhost:9090

本地开发```bash

Install dependencies

pip install -e ".[dev]"

Start Redis and Ollama

redis-server &
ollama serve &

Start the API

uvicorn agents.main:app --reload --port 8000

Start the frontend (separate terminal)

streamlit run frontend/app.py


______________________________________________________________________

## 热交换演示

查看核心价值主张的实际应用——计算器服务器在启动时处于休眠状态,然后在会话中期热插拔:

**零代码更改。零重启。**```bash
bash scripts/load_test.sh
``````
Servers at startup:
- youtube_summary_server  (3 tools, active)
- notes_creator_server    (4 tools, active)
- web_research_server     (3 tools, active)

Dormant: calculator (calculate, percentage, split_bill, unit_convert, loan_emi)

Query 1: "search for latest AI news"     → search_web       hot-plug: NO
Query 2: "say hello in French"           → none (LLM)       hot-plug: NO
Query 4: "calculate 42 * 58"             → calculate        hot-plug: YES ⚡ calculator_server
Query 5: "search for python tutorials"   → search_web       hot-plug: NO  (calculator detached)
Query 8: "calculate 15% of 8500"         → calculate        hot-plug: YES ⚡ fresh plug again
Query 11: "split bill of 2400 for 3"     → split_bill       hot-plug: YES ⚡ third cycle

ALL TESTS PASSED ✓  (12/12)
Hot-plug cycles: attached 3× · detached 3× · perfect symmetry

API终点

方法 端点 描述
POST /query 向路由器代理发送查询
GET /tools 列出所有已注册的工具
GET /servers 列出已连接的MCP服务器
POST /servers/register 注册新的MCP服务器
DELETE /servers/{name} 断开服务器连接
GET /chat/history/{session_id} 获取对话历史记录
DELETE /chat/history/{session_id} 清除会话历史记录
GET /health 健康检查(服务器、工具、Redis)
GET /metrics 普罗米修斯指标

监控

自动配置 MCP助理 Grafana仪表板包括:

面板 公制
查询总数 sum(queries_total)
活动服务器 active_servers_count
可用工具 available_tools_count
错误率 queries_total{status="error"} /总计×100
每分钟查询次数 rate(queries_total[1m]) * 60
响应时间P50/P95/P99 histogram_quantile 超过 query_duration_seconds_bucket
按服务器调用工具 rate(tool_calls_total[5m]) 按服务器
工具响应时间 histogram_quantile(0.95, ...) 通过工具

访问地址: http://localhost:3000 (管理员/管理员)

Grafana屏幕截图


聊天界面


添加自定义工具服务器

将Python文件放入 servers/:```python

servers/my_tools_server.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-tools")

@mcp.tool()
def greet(name: str) -> str:
"""Say hello to someone."""
return f"Hello, {name}!"

if name == "main":
mcp.run(transport="stdio")


通过API注册-无需重新启动:```bash
curl -X POST http://localhost:8000/servers/register \
-H "Content-Type: application/json" \
-d '{"name": "my-tools", "script_path": "servers/my_tools_server.py"}'

代理立即开始将查询路由到您的新工具。


项目结构```

mcp-hotswap-agent/
├── agents/
│ ├── main.py # FastAPI app with all endpoints
│ ├── router_agent.py # LLM-powered tool routing + hot-swap logic
│ ├── mcp_client.py # MCP stdio session manager + AST plugin scanner
│ ├── tool_registry.py # Redis-backed tool storage (Hash + Sorted Set)
│ ├── chat_history.py # Session-isolated conversation persistence
│ ├── config.py # Settings (env vars)
│ └── metrics.py # Prometheus counters / histograms / gauges
├── servers/
│ ├── calculator_server.py # Math, finance, unit conversion (dormant)
│ ├── web_research_server.py # DuckDuckGo search, URL fetch
│ ├── notes_creator_server.py # Markdown notes with YAML frontmatter
│ └── youtube_summary_server.py # Transcript extraction, video Q&A
├── frontend/
│ └── app.py # Streamlit chat UI + server management
├── docker/
│ ├── Dockerfile
│ ├── Dockerfile.frontend
│ └── docker-compose.yml # 7-service orchestration
├── monitoring/
│ ├── prometheus.yml
│ ├── grafana-dashboard.json
│ ├── grafana-datasource.yml
│ └── grafana-dashboard-provider.yml
├── scripts/
│ ├── start.sh # One-command Docker startup
│ ├── load_test.sh # 12-query hot-swap verification test
│ └── e2e_smoke.sh # E2E smoke test against live stack
├── screenshots/
│ ├── architecture.png
│ └── grafana-metrics/
│ ├── metrics_1.png
│ ├── metrics_2.png
│ ├── metrics_3.png
│ └── metrics_4.png
├── tests/
│ ├── test_hotswap.py # Hot-plug lifecycle: attach → execute → detach → rescan
│ ├── test_integration.py # Full API flows (ASGI client + fakeredis)
│ ├── test_error_scenarios.py # Ollama offline, timeout, garbage JSON, tool errors
│ ├── test_param_correction.py # LLM param name correction edge cases
│ ├── test_chat_history.py # Session-isolated Redis chat history
│ └── test_tool_registry.py # Redis registry CRUD
└── pyproject.toml


______________________________________________________________________

## 测试```bash
# Run all 40+ tests
pytest tests/ -v

# Run specific modules
pytest tests/test_hotswap.py -v
pytest tests/test_integration.py -v
pytest tests/test_error_scenarios.py -v

# E2E smoke test (requires docker compose up)
bash scripts/e2e_smoke.sh

# Hot-swap load test (12 queries, 3 hot-plug cycles)
bash scripts/load_test.sh

主要功能(详细)

  • 热插拔生命周期 --休眠扫描→ 热插拔→ 执行→ 自动分离→ 重新扫描,在3个独立循环中通过完美的附着/分离对称性进行验证。
  • 异步会话管理器 背景 asyncio.Task 每个服务器都有停止事件信号,以实现清洁生命周期;连接失败时重试一次;会话丢失时自动重新连接。
  • 并行工具执行 --多工具查询通过以下方式并发调度 asyncio.gather() 具有每个工具的延迟跟踪功能。
  • 参数自动校正 --当参数计数与模式匹配时,LLM键名的位置重新映射不匹配——在4种边缘情况下进行了测试。
  • 测试了5种故障模式 --Ollama离线、ReadTimeout、垃圾JSON(重试+回退)、工具异常传播、合成失败回退到级联。
  • Redis数据模型 — tools:{name} 搞砸, server_tools:{name} 设置, tool_index 排序集, chat:{session_id} capped List——所有操作都通过异步管道实现原子性。

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
MCP Hotswap Agent 怎么安装?

在客户端按下面的安装命令接入:pip install -e ".[dev]"。装完在客户端配置里引用同一个包或端点。

MCP Hotswap Agent 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

MCP Hotswap Agent 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Hotswap Agent 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

MCP Hotswap Agent 能提供哪些能力?

资料显示约 15 个工具;能力标签包括 本地运行、Python、AI代理。具体工具清单以官方文档为准。

MCP Hotswap Agent 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

MCP Hotswap Agent 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。