定位与目标

SLM MCP Hub 是一个面向 AI 编程会话的 Model Context Protocol（MCP）网关。它在 README 中被描述为"世界上第一个会学习的 MCP 网关"，目标是把多个 MCP 服务器、多种传输方式（stdio 与 HTTP）汇聚到一个常驻进程中，让任意 AI 客户端共享同一份联邦化的工具视图 资料来源：README.md:1-15。它属于 Qualixar 智能体可靠性平台的一部分，与 SuperLocalMemory、Qualixar OS、SLM Mesh 等组件并列 资料来源：README.md:18-31。

核心痛点（README 中明确指出）是：每个 AI 编程会话都会独立派生自己的 MCP 进程，造成资源浪费与会话间不可见 资料来源：README.md:33-36。Hub 通过一次启动、按需懒启动、跨会话缓存与会话历史共享来缓解这一问题 资料来源：src/slm_mcp_hub/intelligence/lifecycle.py:8-19、资料来源：src/slm_mcp_hub/intelligence/cache.py:8-15。

核心架构

整个仓库以 slm_mcp_hub 为主包，入口在 cli/main.py 中基于 Click 提供 CLI 工具 slm-hub，CLI 启动后会构造 HubOrchestrator 负责调度 资料来源：src/slm_mcp_hub/cli/main.py:1-31。HubOrchestrator 再把能力委派给一组内部子系统。下图展示了高层组件关系：

flowchart TB
    Client[AI 客户端<br/>Claude Code / Cursor / VS Code]
    CLI[slm-hub CLI]
    Hub[HubOrchestrator]
    Fed[Federation 层<br/>namespace + connection]
    Intel[Intelligence 层<br/>filtering / cache / learning / lifecycle]
    Plugin[Plugin 钩子]
    DB[(SQLite 存储<br/>schema.py)]
    Watchdog[Watchdog / systemd / launchd]

    Client -->|stdio 或 HTTP| CLI
    CLI --> Hub
    Hub --> Fed
    Hub --> Intel
    Hub --> Plugin
    Hub --> DB
    Watchdog -. 守护 .-> CLI

Federation 层负责把多个 MCP 后端的工具/资源/提示（prompts）按 server_id 加双下划线进行命名空间隔离，例如 parse_namespaced("github__create_issue") 会得到 ('github', 'create_issue') 资料来源：src/slm_mcp_hub/federation/namespace.py:1-19。connection.py 则实现 stdio 子进程的 JSON-RPC 收发循环、pending 字典与 stderr 捕获 资料来源：src/slm_mcp_hub/federation/connection.py:1-39。

Intelligence 层在 Hub 中以 4 个子模块实现：

• filtering.py 提供 13 个确定性活动分类（coding、debugging、testing 等），按工具名关键字做归类以节省 token 资料来源：src/slm_mcp_hub/intelligence/filtering.py:18-35。
• cache.py 通过 SHA-256 前 16 位对参数做内容哈希，并维护一张不可缓存工具名单（remember、create_issue 等有副作用的工具）资料来源：src/slm_mcp_hub/intelligence/cache.py:17-31。
• learning.py 维护 ToolCallRecord 与 Counter，统计调用频次、成功率与 60 秒内的工具链 资料来源：src/slm_mcp_hub/intelligence/learning.py:14-39。
• lifecycle.py 追踪每个 server 的最近调用时间，配合 IDLE_SHUTDOWN_SECONDS 做懒启动与空闲关闭 资料来源：src/slm_mcp_hub/intelligence/lifecycle.py:8-30。

主要能力

配置与运行入口

配置层由 core/config.py 中的两个不可变 dataclass 组成：MCPServerConfig（name/transport/command/args/env/url/headers/enabled/always_on/no_cache/cost_per_call_cents）与 HubConfig（host/port/mcp_servers/session_timeout/max_sessions/cache_ttl/cache_max_entries 等） 资料来源：src/slm_mcp_hub/core/config.py:23-55。CLI 在启动前会从 ~/.claude-secrets.env 与 ~/.slm-mcp-hub/secrets.env 加载密钥，使 ${VAR} 占位符与 Claude Code 共享同一份环境变量 资料来源：src/slm_mcp_hub/cli/main.py:21-44。

扩展点采用 Python entry_points 风格的 HubPlugin 抽象类，钩子涵盖 on_hub_start / on_hub_stop / on_tool_call_before / on_tool_call_after / on_session_start 等 资料来源：src/slm_mcp_hub/plugins/base.py:1-46。

版本与生态

__init__.py 中显式声明的版本为 0.1.2 资料来源：src/slm_mcp_hub/__init__.py:3。CHANGELOG 显示 0.2.0 起引入了"生命周期与传输"重大更新，0.2.1 文档化了 Gamma MCP 通过 X-API-KEY 头接入的方式，0.2.3 则把 hub__search_tools 等元工具改名为 search_tools，并把默认调用超时收敛到 2 分钟，同时保留 _META_TOOL_ALIASES 以兼容旧客户端 资料来源：CHANGELOG.md:1-30。项目维护者为 Varun Pratap Bhardwaj，遵循 AGPL v3 许可 资料来源：AUTHORS.md:3-5、资料来源：README.md:13。

参见

• 联邦命名空间（federation/namespace）
• 智能缓存（intelligence/cache）
• 生命周期管理（intelligence/lifecycle）
• 学习引擎（intelligence/learning）
• CLI 入口与配置（cli/main、core/config）
• 插件接口（plugins/base）

概览与定位

src/slm_mcp_hub/ 是 SLM MCP Hub 的核心 Python 包，承载"一个 hub 进程、聚合所有 MCP 服务器、对所有 AI 客户端共享"的设计目标。包内按职责拆分为 core/、federation/、intelligence/、lifecycle/、discovery/、storage/、resilience/、cli/ 等子包，对外统一暴露 430+ MCP 工具，对内承担配置加载、命名空间隔离、按需启停、调用学习与成本核算等智能层职责。资料来源：README.md:1-50

顶层目录结构

下表概览主要子包及其代表文件：

资料来源：README.md:1-50、storage/schema.py:1-30、core/config.py:23-63

关键子系统详解

配置与命名空间

MCPServerConfig 是冻结 dataclass，仅描述单个联邦 MCP 的 transport、command / url、headers、always_on、cost_per_call_cents 等字段；HubConfig 则是整体配置，含 host、port、mcp_servers、session_timeout_seconds、cache_ttl_seconds 等。资料来源：core/config.py:23-63

federation/namespace.py 提供联邦协议所需的所有命名空间工具：safe_server_id、namespace_name、parse_namespaced、namespace_tool、namespace_resource、namespace_prompt 等，反向解析时"在第一个分隔符处切分，保留原始名中的后续下划线"，例如 remote__github__search → ('remote', 'github__search')。资料来源：federation/namespace.py:1-100

智能层：过滤、学习、成本、生命周期

• 过滤：filtering.py 定义 13 类确定性活动（coding / debugging / testing / planning / delegation / git_ops / research / documentation / build_deploy / data / media / memory / exploration），纯字符串匹配，不调用任何 LLM；同时按文件扩展名推断 python / typescript / rust / data 等项目类型，配合 Meta-MCP 模式节省 token。资料来源：intelligence/filtering.py:1-60
• 学习：learning.py 内 LearningEngine 在内存中跟踪调用频次、成功率与"60 秒内的工具链"（CHAIN_WINDOW_SECONDS = 60.0），并附带 slow_threshold_ms = 10_000 慢调用告警，最多保留 10_000 条记录。资料来源：intelligence/learning.py:1-60
• 成本：cost.py 内置 DEFAULT_COST_TABLE，预先为 Perplexity、Tavily、Exa、Gemini、fal.ai、Firecrawl 等按计费 MCP 设置单次调用价（单位：美分），并通过 load_cost_table_from_file 接受用户 JSON 覆盖，且未来计划对接 LiteLLM model_cost 自动更新。资料来源：intelligence/cost.py:1-60
• 生命周期：intelligence/lifecycle.py 的 LifecycleManager 记录每个 server 的 last_call 时间戳，对非 always_on 服务器执行按需启动与空闲关停（默认 IDLE_SHUTDOWN_SECONDS）。资料来源：intelligence/lifecycle.py:1-60

连接、热重载与自动注册

federation/connection.py 实现 stdio 子进程 + JSON-RPC 主循环：从 _process.stdout 逐行读取 NDJSON，按 id 派发到 _pending 字典中的 Future；空行或非 JSON 行被静默忽略。当子进程立即 EOF 且 stderr 为空时，诊断信息会提示 "verify the command is an MCP server, not a one-shot command"。资料来源：federation/connection.py:1-60

lifecycle/__init__.py 标注 "runtime graph, config diffing, hot-reload, drain, notifications"，与 v0.2.0 发布说明中 Zero-restart hot-reload 完全对应——可通过 slm-hub server add / remove / modify 运行时改联邦，无需重启 hub。资料来源：lifecycle/__init__.py:1-5、README.md:1-30

discovery/auto_register.py 的 _build_hub_entry 同时支持两种传输：HTTP（Claude Code / VS Code Copilot / Cursor / Windsurf / Codex CLI 使用 {"type":"http","url":...}）与 stdio（Claude Desktop 使用 {"command":"slm-hub","args":["mcp"]}，让客户端把 hub 当成子进程拉起）。资料来源：discovery/auto_register.py:1-60

CLI 入口、密钥与弹性

cli/main.py 是 slm-hub 命令根入口，启动时通过 SECRETS_PATHS = (~/.claude-secrets.env, ~/.slm-mcp-hub/secrets.env) 加载密钥；解析每行 KEY=VALUE 时，仅当 key 尚未存在于 os.environ 才注入，从而保留显式值优先。资料来源：cli/main.py:1-60

cli/setup_commands.py 暴露 setup detect 与 network 子命令：ClientDetector.detect_all() 扫描本机 AI 客户端并报告 mcp_count、hub_registered；NetworkDiscovery 基于 zeroconf 的 SERVICE_TYPE 做局域网发现。资料来源：cli/setup_commands.py:1-60

resilience/watchdog.py 生成 systemd unit（Restart=always、RestartSec=5）与 macOS launchd plist，并维护 PID 文件，让 hub 进程崩溃后自动拉起，与 v0.2.3 引入的 DEFAULT_TOOL_TIMEOUT_S = 120（per-call timeout）共同构成"失败快、失败可恢复"的两道防线。资料来源：resilience/watchdog.py:1-60、README.md:1-30

一次工具调用的主路径

flowchart LR
    A[AI 客户端<br/>Claude Code / Cursor / ...] -->|HTTP 或 stdio| B[cli/main.py<br/>Hub 入口]
    B --> C[core/config.py<br/>HubConfig + MCPServerConfig]
    C --> D[federation/namespace.py<br/>server__tool 命名]
    D --> E[federation/connection.py<br/>JSON-RPC over stdio]
    E --> F[intelligence/filtering.py<br/>活动分类 + 项目类型]
    F --> G[intelligence/learning.py<br/>频次 / 链路 / 慢调用]
    G --> H[intelligence/cost.py<br/>预算 + 级联降级]
    H --> I[intelligence/lifecycle.py<br/>按需启停 / idle shutdown]
    I --> J[storage/schema.py<br/>tool_calls + cache]
    J -->|写入 SQLite| K[(hub.db)]

失败模式与扩展点

• 密钥加载失败：cli/main.py 的 _load_secrets() 对不存在的 secrets 文件静默跳过，对解析异常同样宽容，配置仍可使用。资料来源：cli/main.py:1-60
• 错把一次性命令当作 MCP 服务器：stdio 子进程立即 EOF 且 stderr 为空时，federation/connection.py 的诊断文案会指引用户核实。资料来源：federation/connection.py:1-60
• 成本表覆盖：在不改源码的前提下，通过 JSON 文件传入 load_cost_table_from_file 覆盖 DEFAULT_COST_TABLE 中任意条目；v0.2.1 说明也利用此机制通过 headers 字段把 Gamma 等仅支持 X-API-KEY 的 MCP 联邦进来。资料来源：intelligence/cost.py:1-60、README.md:1-30
• 运行时扩缩：v0.2.0 起 slm-hub server add / remove 即可热重载；运行时图与 drain 流程位于 lifecycle/ 子包。资料来源：lifecycle/__init__.py:1-5、README.md:1-30

See Also

• 核心模块（core） — HubConfig / MCPServerConfig / HubOrchestrator 详解
• 联邦层（federation） — namespace 与 connection 子包深入剖析
• 智能层（intelligence） — filtering / learning / cost / lifecycle
• CLI 命令 — setup、server、detect、network 命令族
• Qualixar 平台 — README.md 中六款产品矩阵与论文索引

资料来源：README.md:1-30、AUTHORS.md:1-20

概述

server 模块是 SLM MCP Hub 对外提供服务的传输层入口，负责把联邦化的 MCP（Model Context Protocol）能力以 两种传输协议 暴露给上游 AI 客户端：标准的 HTTP/SSE（基于 FastAPI）以及兼容 Claude Desktop 的 stdio NDJSON。该模块的目标是「一个 hub 进程对接所有 MCP 服务器与所有 AI 客户端」，并复用同一份会话、注册表、生命周期与代理逻辑。

资料来源：src/slm_mcp_hub/server/__init__.py，src/slm_mcp_hub/server/http_server.py:35-58

根据 v0.2.0 的发布说明，「首个同时原生支持 stdio 与 HTTP 的 MCP 网关」即由该模块承担（v0.2.0 release notes）。

模块组成

server 子包由四个相互协作的组件构成：

资料来源：src/slm_mcp_hub/server/http_server.py:11-23

HTTP 服务器

create_app() 是 HTTP 入口的工厂函数，接收联邦化端点、会话管理器、可选的连接管理器与重载器，返回一个配置完成的 FastAPI 实例。关键设计点包括：

• CORS 中间件：默认放行所有来源，并显式暴露 Mcp-Session-Id 响应头，便于 MCP 会话追踪。
• MCP 协议端点：所有 MCP JSON-RPC 请求统一路由至 MCPEndpoint 处理。
• 运维端点：
• GET /api/v1/status 返回 hub 详细状态；
• GET /api/v1/session-greeting 返回精简的工具清单，可在 Claude 会话启动时注入上下文；
• GET /api/v1/servers/detail 列出每台服务器的 configured | connected | tools | error 状态；
• POST /api/v1/reload 重读磁盘 config.json，调用 Reloader.apply_config() 应用 diff，实现 v0.2.0 强调的「零重启热重载」。

资料来源：src/slm_mcp_hub/server/http_server.py:62-130

Stdio 传输

对于不支持 HTTP 的客户端（如 Claude Desktop），hub 通过 stdio 暴露相同的能力。其客户端入口形式由 discovery/auto_register.py 中的 _build_hub_entry() 生成：

{
  "command": "slm-hub",
  "args": ["mcp"],
  "env": { ... }
}

客户端把 slm-hub mcp 作为子进程拉起，双方通过 stdin/stdout 交换 NDJSON 封装的 JSON-RPC 消息——无需 Node 桥接、无需 localhost 绑定，与 HTTP 路径共享同一套联邦化与会话逻辑。

资料来源：src/slm_mcp_hub/discovery/auto_register.py:24-42，src/slm_mcp_hub/cli/main.py:18-35

传输对比与选型

flowchart LR
    A[AI 客户端] -->|HTTP/SSE| B[http_server.create_app]
    A -->|stdio NDJSON| C[stdio_server<br/>slm-hub mcp]
    B --> D[MCPEndpoint<br/>联邦化 JSON-RPC]
    C --> D
    D --> E[Registry<br/>命名空间 + 元数据]
    D --> F[SessionManager]
    D --> G[ConnectionManager<br/>下游 MCP 服务器]
    H[POST /api/v1/reload] --> I[Reloader<br/>apply_config]
    I --> G

常见失败模式

1. 下游 MCP 子进程无 stderr 输出：connection.py 会在状态描述中提示「verify the command is an MCP server, not a one-shot command」，常因把一次性 CLI 误配为 MCP 服务器导致。
2. JSON 解析错误：非 JSON 行被记录为 debug 日志而非抛出，确保单条坏消息不会让整个 stdio 循环退出。
3. 重载失败：POST /api/v1/reload 捕获 ReloadError 并返回 {"success": false, "error": str(exc)}，调用方应据此回滚或重试。

资料来源：src/slm_mcp_hub/server/http_server.py:118-128，src/slm_mcp_hub/federation/connection.py:60-75

See Also

• Federation 模块 — 命名空间与能力联邦
• Lifecycle 模块 — 热重载、drain 与通知
• Core 模块 — 配置、会话、注册表
• CLI 模块 — slm-hub 命令行入口

模块定位与入口

Cli 模块是 SLM MCP Hub 的命令行前端，基于 Click 框架组织命令子分组，承担运维、初始化、客户端发现与服务编排等所有用户面交互。其入口 main.py 同时承载 CLI 启动、密钥预加载以及顶层命令树的挂载，是用户与 hub 守护进程交互的唯一官方途径。资料来源：src/slm_mcp_hub/cli/main.py:1-49。

入口处通过 _load_secrets() 在 CLI 启动前解析两份本地密钥文件——~/.claude-secrets.env（与 Claude Code 共享）与 ~/.slm-mcp-hub/secrets.env（hub 专属）——并把其中的 KEY=VALUE 注入到 os.environ。该机制确保用户在 MCP 服务器配置中使用的 ${VAR} 占位符能解析到与 Claude Code 一致的变量值，避免多客户端之间密钥漂移。资料来源：src/slm_mcp_hub/cli/main.py:19-49。

命令分组结构

CLI 在 main.py 中通过 Click 装饰器挂载三个顶层命令组：

资料来源：src/slm_mcp_hub/cli/main.py:13-16、src/slm_mcp_hub/cli/setup_commands.py:1-30。setup 与 server 均为 Click @click.group()，因此可继续通过 slm-hub server add … 等嵌套形式扩展子命令。

社区证据显示，slm-hub server add github --command npx --arg @modelcontextprotocol/server-github 与 slm-hub server remove … 等热重载命令自 v0.2.0 起即在 server 组中可用，新增、移除、修改联邦服务器无需重启 hub 进程。资料来源：v0.2.0 发布说明。

客户端发现与自动注册

setup 子命令组以 ClientDetector 与 AutoRegister 两个发现组件为底座，提供"探测—展示—写入"三步式引导：

flowchart LR
    A[slm-hub setup detect] --> B[ClientDetector.detect_all]
    B --> C{输出格式}
    C -->|人类可读| D[对齐表格: 名称/MCP数/Hub?/路径]
    C -->|JSON| E[结构化清单]
    F[slm-hub setup ...] --> G[AutoRegister 注册计划]
    G --> H[写入 ~/.claude.json 等客户端配置]

setup_detect 命令支持 --json-output 开关，命令行表格列依次为「Client / MCPs / Hub? / Config Path」，便于运维快速判断哪些 AI 客户端已注册到 hub。资料来源：src/slm_mcp_hub/cli/setup_commands.py:18-50。

AutoRegister 在 auto_register.py 中通过 _build_hub_entry 同时支持 HTTP 与 stdio 两种传输：HTTP 模式下写入 {"type": "http", "url": hub_url}（适用于 Claude Code、VS Code Copilot、Cursor、Windsurf、Codex CLI）；stdio 模式下写入 {"command": "slm-hub", "args": ["mcp"], "env": {...}}，由客户端把 slm-hub mcp 作为子进程拉起并通过 stdin/stdout 交换 NDJSON，无需 Node 桥接与本地端口绑定。资料来源：src/slm_mcp_hub/discovery/auto_register.py:1-32。

配置与网络发现

CLI 在初始化阶段调用 core/config.py 中的 load_config() 与 save_config()，并在 import_claude_config / import_vscode_config 导入器中复用相同数据结构，从而保证用户从其他 AI 客户端迁移到 hub 时无需手工重写配置。资料来源：src/slm_mcp_hub/cli/main.py:6-13、src/slm_mcp_hub/core/config.py:1-40。

setup 组中包含 network 命令，通过 NetworkDiscovery 配合 zeroconf（mDNS）在局域网内发布或发现其他 hub 实例；环境未安装 zeroconf 时通过 is_zeroconf_available() 优雅降级，保证 CLI 在无 mDNS 环境下仍可执行其余子命令。资料来源：src/slm_mcp_hub/cli/setup_commands.py:1-17。

常见使用模式

• 首次安装：slm-hub setup detect → slm-hub setup（按提示把 hub 写入 Claude Code / VS Code 等客户端配置）。
• 运行时扩展联邦：slm-hub server add <name> --command …（v0.2.0 起支持热重载，无需重启 hub）。
• HTTP 联邦含自定义请求头：X-API-KEY 等头可在 per-server headers 配置中声明，自 v0.2.1 起用于 Gamma 等同时支持 Bearer 与 API Key 的 MCP 服务器。资料来源：v0.2.1 发布说明。
• 密钥管理：在 ~/.claude-secrets.env 或 ~/.slm-mcp-hub/secrets.env 中以 KEY=VALUE 形式注入，CLI 启动时自动加载到 os.environ。资料来源：src/slm_mcp_hub/cli/main.py:19-49。

See Also

• 核心配置：core/config.py
• 客户端发现：discovery/client_detector.py
• 网络发现：discovery/network.py
• 自动注册：discovery/auto_register.py

Pitfall Log / 踩坑日志

项目：qualixar/slm-mcp-hub

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1211447212 | https://github.com/qualixar/slm-mcp-hub | release_recency=unknown