# https://github.com/qualixar/slm-mcp-hub 项目说明书

生成时间：2026-06-12 05:29:13 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-src)
- [Server 模块](#page-src-slm_mcp_hub-server)
- [Cli 模块](#page-src-slm_mcp_hub-cli)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/qualixar/slm-mcp-hub/blob/main/README.md)
- [CHANGELOG.md](https://github.com/qualixar/slm-mcp-hub/blob/main/CHANGELOG.md)
- [src/slm_mcp_hub/__init__.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/__init__.py)
- [src/slm_mcp_hub/core/config.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py)
- [src/slm_mcp_hub/federation/namespace.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/federation/namespace.py)
- [src/slm_mcp_hub/federation/connection.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/federation/connection.py)
- [src/slm_mcp_hub/discovery/auto_register.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py)
- [src/slm_mcp_hub/intelligence/filtering.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/filtering.py)
- [src/slm_mcp_hub/intelligence/learning.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/learning.py)
- [src/slm_mcp_hub/intelligence/cache.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/cache.py)
- [src/slm_mcp_hub/intelligence/lifecycle.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/lifecycle.py)
- [src/slm_mcp_hub/lifecycle/__init__.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/lifecycle/__init__.py)
- [src/slm_mcp_hub/storage/schema.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/storage/schema.py)
- [src/slm_mcp_hub/plugins/base.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/plugins/base.py)
- [src/slm_mcp_hub/cli/main.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)
- [src/slm_mcp_hub/resilience/watchdog.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/resilience/watchdog.py)
- [AUTHORS.md](https://github.com/qualixar/slm-mcp-hub/blob/main/AUTHORS.md)
</details>

# 项目概览

## 定位与目标

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` 再把能力委派给一组内部子系统。下图展示了高层组件关系：

```mermaid
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]()。

## 主要能力

| 能力 | 实现位置 | 行为摘要 |
|------|----------|----------|
| 联邦命名空间 | `federation/namespace.py` | 为 tool、resource、resource template、prompt 添加 `server__name` 前缀 |
| 智能缓存 | `intelligence/cache.py` | TTL+LRU，绕过有副作用工具的 `DEFAULT_NO_CACHE_TOOLS` |
| 学习引擎 | `intelligence/learning.py` | 频次/成功率/工具链，内存上限 10 000 条 |
| 懒启动与空闲回收 | `intelligence/lifecycle.py` | 配合 `always_on` 标记关键 MCP |
| 零停机热重载 | `lifecycle/__init__.py` | 运行时增删改联邦 server，无需重启 |
| 客户端自动注册 | `discovery/auto_register.py` | 同时支持 HTTP（`{"type":"http","url":...}`）与 stdio（`slm-hub mcp` 子进程）两种入口 |
| 持久化与遥测 | `storage/schema.py` | SQLite 表：`hub_config`、`mcp_servers`、`sessions`、`tool_calls`、`cache` |
| 进程守护 | `resilience/watchdog.py` | 提供 systemd unit、launchd plist 与 PID 文件 |

## 配置与运行入口

配置层由 `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）](federation-namespace.md)
- [智能缓存（intelligence/cache）](intelligence-cache.md)
- [生命周期管理（intelligence/lifecycle）](intelligence-lifecycle.md)
- [学习引擎（intelligence/learning）](intelligence-learning.md)
- [CLI 入口与配置（cli/main、core/config）](cli-and-config.md)
- [插件接口（plugins/base）](plugins-base.md)

---

<a id='page-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Server 模块](#page-src-slm_mcp_hub-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/slm_mcp_hub/intelligence/filtering.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/filtering.py)
- [src/slm_mcp_hub/intelligence/learning.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/learning.py)
- [src/slm_mcp_hub/intelligence/cost.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/cost.py)
- [src/slm_mcp_hub/intelligence/lifecycle.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/intelligence/lifecycle.py)
- [src/slm_mcp_hub/federation/namespace.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/federation/namespace.py)
- [src/slm_mcp_hub/federation/connection.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/federation/connection.py)
- [src/slm_mcp_hub/lifecycle/__init__.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/lifecycle/__init__.py)
- [src/slm_mcp_hub/discovery/auto_register.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py)
- [src/slm_mcp_hub/storage/schema.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/storage/schema.py)
- [src/slm_mcp_hub/core/config.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py)
- [src/slm_mcp_hub/cli/main.py](https://github.com/qualixar/slm-mcp_hub/blob/main/src/slm_mcp_hub/cli/main.py)
- [src/slm_mcp_hub/cli/setup_commands.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/setup_commands.py)
- [src/slm_mcp_hub/resilience/watchdog.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/resilience/watchdog.py)
</details>

# Src 模块

## 概览与定位

`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]()

## 顶层目录结构

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

| 子包 | 代表文件 | 主要职责 |
|------|----------|----------|
| `core/` | [config.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py) | 加载/保存 hub 配置，定义 `MCPServerConfig` 与 `HubConfig` 不可变 dataclass |
| `federation/` | [namespace.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/federation/namespace.py)、[connection.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/federation/connection.py) | 工具/资源/提示词命名空间隔离、子进程 JSON-RPC 连接 |
| `intelligence/` | [filtering.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/filtering.py)、[learning.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/learning.py)、[cost.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/cost.py)、[lifecycle.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/lifecycle.py) | 项目类型推断、活动分类、调用学习、成本核算、按需启停 |
| `lifecycle/` | [__init__.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/lifecycle/__init__.py) | 运行时图、配置 diff、零停机热重载、drain 与通知 |
| `discovery/` | [auto_register.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py) | 自动写入 Claude Code / VS Code 等客户端配置 |
| `storage/` | [schema.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/storage/schema.py) | SQLite 表结构（`hub_config`、`mcp_servers`、`sessions`、`tool_calls`、`cache` 等） |
| `resilience/` | [watchdog.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/resilience/watchdog.py) | systemd / launchd 单元、PID 文件、auto-restart |
| `cli/` | [main.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)、[setup_commands.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/setup_commands.py) | `slm-hub` 命令行入口、setup / detect / network 子命令族 |

资料来源：[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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/learning.py) 内 `LearningEngine` 在内存中跟踪调用频次、成功率与"60 秒内的工具链"（`CHAIN_WINDOW_SECONDS = 60.0`），并附带 `slow_threshold_ms = 10_000` 慢调用告警，最多保留 10_000 条记录。资料来源：[intelligence/learning.py:1-60]()
- **成本**：[cost.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/intelligence/lifecycle.py) 的 `LifecycleManager` 记录每个 server 的 `last_call` 时间戳，对非 `always_on` 服务器执行按需启动与空闲关停（默认 `IDLE_SHUTDOWN_SECONDS`）。资料来源：[intelligence/lifecycle.py:1-60]()

### 连接、热重载与自动注册

[federation/connection.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/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]()

## 一次工具调用的主路径

```mermaid
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](https://github.com/qualixar/slm-mcp-hub/blob/main/README.md) 中六款产品矩阵与论文索引

资料来源：[README.md:1-30]()、[AUTHORS.md:1-20]()

---

<a id='page-src-slm_mcp_hub-server'></a>

## Server 模块

### 相关页面

相关主题：[Src 模块](#page-src), [Cli 模块](#page-src-slm_mcp_hub-cli)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/slm_mcp_hub/server/__init__.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/server/__init__.py)
- [src/slm_mcp_hub/server/http_server.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/server/http_server.py)
- [src/slm_mcp_hub/server/mcp_endpoint.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/server/mcp_endpoint.py)
- [src/slm_mcp_hub/server/proxy_endpoint.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/server/proxy_endpoint.py)
- [src/slm_mcp_hub/server/stdio_server.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/server/stdio_server.py)
</details>

# Server 模块

## 概述

`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](https://github.com/qualixar/slm-mcp-hub/releases/tag/v0.2.0)）。

## 模块组成

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

| 组件 | 文件 | 角色 |
|------|------|------|
| `http_server` | `http_server.py` | 基于 FastAPI 创建 HTTP 应用，挂载 CORS、状态/会话问候/重载等 REST 端点 |
| `mcp_endpoint` | `mcp_endpoint.py` | 处理联邦化 MCP JSON-RPC 请求（`tools/list`、`tools/call` 等）的核心端点 |
| `proxy_endpoint` | `proxy_endpoint.py` | 透传/代理上游 MCP 流量，保持与原始 MCP 协议兼容 |
| `stdio_server` | `stdio_server.py` | 通过 `slm-hub mcp` 子进程提供 stdio NDJSON 传输，供 Claude Desktop 等仅支持 stdio 的客户端使用 |

资料来源：[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()` 生成：

```json
{
  "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]()

## 传输对比与选型

```mermaid
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
```

| 维度 | HTTP 传输 | Stdio 传输 |
|------|----------|-----------|
| 适用客户端 | Claude Code、VS Code Copilot、Cursor、Windsurf、Codex CLI | Claude Desktop 等仅支持 stdio 的客户端 |
| 进程模型 | 客户端连到 hub URL | 客户端把 hub 作为子进程启动 |
| 数据格式 | JSON-RPC over HTTP + SSE | JSON-RPC over NDJSON（stdin/stdout） |
| 额外桥接 | 不需要 | 不需要（无 Node 桥、无 localhost 绑定） |
| 热重载 | `POST /api/v1/reload` 即可 | 同一套重载逻辑，客户端重启即生效 |

## 常见失败模式

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 模块](federation-module.md) — 命名空间与能力联邦
- [Lifecycle 模块](lifecycle-module.md) — 热重载、drain 与通知
- [Core 模块](core-module.md) — 配置、会话、注册表
- [CLI 模块](cli-module.md) — `slm-hub` 命令行入口

---

<a id='page-src-slm_mcp_hub-cli'></a>

## Cli 模块

### 相关页面

相关主题：[Server 模块](#page-src-slm_mcp_hub-server)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/slm_mcp_hub/cli/__init__.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/__init__.py)
- [src/slm_mcp_hub/cli/main.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)
- [src/slm_mcp_hub/cli/server_commands.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/server_commands.py)
- [src/slm_mcp_hub/cli/setup_commands.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/setup_commands.py)
- [src/slm_mcp_hub/discovery/auto_register.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py)
- [src/slm_mcp_hub/discovery/client_detector.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/client_detector.py)
- [src/slm_mcp_hub/core/config.py](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py)

</details>

# Cli 模块

## 模块定位与入口

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

入口处通过 `_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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)。

## 命令分组结构

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

| 命令组 | 挂载位置 | 主要职责 |
|--------|----------|----------|
| `setup` | `setup_commands.py` | 客户端探测、配置导入、网络发现、自动注册 |
| `server` | `server_commands.py` | 联邦 MCP 服务器的增删改查、运行时热重载 |
| （隐式 `start` 等） | `main.py` 内联 | 启动 `HubOrchestrator` 守护进程、加载 `HubConfig` |

资料来源：[src/slm_mcp_hub/cli/main.py:13-16](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)、[src/slm_mcp_hub/cli/setup_commands.py:1-30](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/setup_commands.py)。`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 发布说明](https://github.com/qualixar/slm-mcp-hub/releases/tag/v0.2.0)。

## 客户端发现与自动注册

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

```mermaid
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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/setup_commands.py)。

`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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py)。

## 配置与网络发现

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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)、[src/slm_mcp_hub/core/config.py:1-40](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py)。

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

## 常见使用模式

- **首次安装**：`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 发布说明](https://github.com/qualixar/slm-mcp-hub/releases/tag/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](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/cli/main.py)。

## See Also

- 核心配置：[`core/config.py`](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/core/config.py)
- 客户端发现：[`discovery/client_detector.py`](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/client_detector.py)
- 网络发现：[`discovery/network.py`](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/network.py)
- 自动注册：[`discovery/auto_register.py`](https://github.com/qualixar/slm-mcp-hub/blob/main/src/slm_mcp_hub/discovery/auto_register.py)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: qualixar/slm-mcp-hub; human_manual_source: deepwiki_human_wiki -->