MCP Manager

Python MCP 管理与代理网关，提供独立 Web 管理台、Token 授权、缓存工具目录及按会话复用的懒加载运行时。系统独立保存配置，不修改 Codex 的 config.toml。

安装与启动

需要 uv。从本地构建好的 wheel 安装（Windows / Linux）：

uv tool install ./dist/mcp_manager_gateway-0.1.3-py3-none-any.whl
mcp-manager

安装后提供三个等价命令：mmg、mcp-manager、mcp-manager-gateway，均支持本文的全部子命令和参数。mcp-manager 默认启动 Web 服务，也可执行 mcp-manager serve。使用 -h / --help 查看帮助，-v / --version 查看安装版本。无需进入源码目录。包发布到 PyPI 后，可使用 uv tool install mcp-manager-gateway；本仓库的构建操作不会自动发布到 PyPI。

打开 http://127.0.0.1:8765 。首次注册账户为管理员，密码至少 10 个字符。

首次启动自动建立用户目录、.env、SQLite 数据库和密钥，并执行数据库迁移：

• Windows：C:\Users\用户名\.mcp-manager
• Linux：~/.mcp-manager

工具目录集中保存在 cache/catalog.jsonl，后台任务状态集中保存在 jobs/jobs.jsonl。缓存文件缺失时，启动后会在后台为已启用服务重建目录，按需服务发现完成即释放实例；仍会禁用发现失败的服务。更新采用追加写入，自动合并重复快照；缓存按服务和授权用户保存最新版本，不再按版本创建文件。启动时会迁移可读取的旧 .json 快照，持久化成功后删除旧文件；无法读取的文件会保留并记录迁移错误。日志仍按日期保存为 JSONL，系统数据库、日志 SQLite 索引与 .env 保持各自格式。

环境变量优先于用户目录内的 .env；源码目录和当前工作目录的 .env 不会被自动读取。可设置 MCP_MANAGER_HOME，或执行 mcp-manager --home /自定义目录 serve 指定另一份配置与数据。

修改用户目录下的 .env 后重启服务。更换端口可修改 PORT；使用 OAuth 时还需同步 PUBLIC_URL 中的回调地址。也可执行：

mcp-manager serve --port 8766

控制台按浏览器实际访问地址识别同源请求，可使用 localhost、内网 IP 或域名登录，无需把每个地址加入白名单。PUBLIC_URL 用于 OAuth 回调，也作为反向代理场景的额外可信来源。远程访问设置 HOST=0.0.0.0，例如通过 http://192.168.2.111:8765 打开控制台。HTTPS 反向代理场景设置 PUBLIC_URL=https://你的域名、COOKIE_SECURE=true。配置示例见 .env.example。

使用顺序

1. 管理员添加 MCP。支持 stdio、Streamable HTTP、旧 SSE、REST 转 MCP；http 是 Streamable HTTP 的导入别名。
2. 添加或修改启用中的 MCP 后自动发现工具；连接启动时再次更新缓存。lazy 的维护发现完成后释放实例。非 OAuth 服务的启动、连接或发现失败会自动将运行策略设为 disabled，移除可用工具目录并保留失败原因。OAuth 未授权、过期或发现失败只清除当前用户的目录和实例，保留服务运行策略，不影响其他用户。配置仍会保存，便于修复；修复后管理员可点击启动、刷新自动禁用的服务，或重新设置 lazy/eager，读取最新工具成功才恢复可用目录。自动禁用后的重试恢复此前策略；旧记录未保存此前策略时默认 lazy。手动禁用的服务仅在显式启动或设置启用策略后恢复，刷新不会自行启用。已禁用的 OAuth 服务仍可完成授权，但授权不会自动启用服务。REST 刷新会先探测 HTTP 连接，不能仅凭本地定义生成可用缓存。
3. 给普通用户分配可用 MCP；用户只能在自己的授权范围创建 Token。
4. 在访问令牌页面创建凭据并配置客户端。令牌值加密保存，可在列表复制或编辑时查看。旧版本仅保存哈希的令牌无法还原，轮换一次后即可回显和复制。普通用户只管理自己的令牌；管理员默认查看自己的令牌，可切换全部用户并按用户名筛选。
5. 实际调用才启动按需服务。查询工具目录不会启动下游进程。

REST 默认向工具地址发送 HEAD 请求检查连接，HTTP 405 表示该路由不支持 HEAD，视为连通；连接失败、鉴权失败、404 或服务器错误会使发现失败。可在表单中填写健康检查 URL（配置字段 healthcheck_url），改用 GET 检查固定健康端点并要求 2xx；工具 URL 含参数时必须配置该地址。此检查不执行 POST、PUT、DELETE 等业务工具，也不代替具体工具的功能测试。

管理员可新建、修改、复制、搜索、筛选、分页和批量处理 MCP；支持通用 JSON、Codex TOML、Claude 和 DSH Cordis/registry 导入、诊断、去重、导入冲突策略、脱敏导出、缓存刷新和真实工具测试。批量工具测试运行保存的显式参数用例；先检查参数再执行可能产生写入的工具。

服务标识 slug 是稳定的工具路由名称，创建后不修改；需要新的标识时创建副本。原生工具名通常为 slug__tool，过长或含特殊字符时会生成稳定的短名称。输入 Schema、结构化结果、文本、图像、音频及资源/提示词都通过 MCP 协议返回。

HTTP 接入

统一端点：POST/GET/DELETE /mcp，使用 MCP Streamable HTTP 客户端。

Authorization: Bearer mcpm_你的Token

原生工具目录直接列出该 Token 有权使用的全部缓存工具。按需发现提供两个索引工具和一个执行工具：

mcp 推荐使用返回的服务 ID，也支持名称和 slug。指定 mcp、tool 留空会列出该服务全部工具；mcp 留空或为 * 时跨服务搜索；两个参数都留空或为 * 时列举全部授权 MCP 和工具。超过页大小时跟随 next_cursor，保持查询不变。每页条目还有 1 MiB 的累计 JSON 字节预算，完整 Schema 不拆分；单个条目超过此预算时返回 catalog_entry_too_large。错误参数会返回字段路径和修正提示，实际执行不会通过模糊匹配选择工具。

管理员可在「系统设置 → 工具检索」配置 OpenAI 兼容 embedding 接口、模型、密钥、超时与最低相似度，并测试已保存的连接。例如接口 https://api.siliconflow.cn、模型 BAAI/bge-m3；也可接本地模型。裸地址自动补全 /v1/embeddings，支持 /v1 或完整 embeddings 地址。

精确名称优先，其他查询融合字段关键词、拼写模糊匹配和真实向量相似度。向量默认关闭；启用后模型故障会明确回退关键词模式。最低相似度默认 0.5；已有管理员自定义值保持不变，并应结合所选模型和实际查询评估。单次超过 1,000 个候选时语义阶段返回 input_too_large 并回退关键词，完整目录分页仍可用。文档向量和查询向量均缓存，并按接口、模型、授权身份和内容隔离，使同一查询的分页评分保持稳定；仅向模型发送描述性元数据与检索语句，不发送连接凭据或实际调用参数。重排序模型使用独立的 rerank 协议，不能填入 embedding 模型栏。

关闭 Token 鉴权只影响 MCP 调用，Web 管理仍需登录。匿名范围由管理员单独设置，默认不公开任何服务。请求提供了无效 Token 时，不会退回匿名权限。

系统设置中的跨域来源默认 *，作用于 /mcp 与 /gateway/v1，支持浏览器 Bearer 请求和预检；可改为指定来源列表，保存后立即生效。管理 API 的 Cookie、CSRF 与同源检查保持独立。

匿名客户端如果显式创建 /gateway/v1/leases 租约，需要保存响应中的 client_secret，并在后续调用、心跳、释放时携带 X-MCP-Manager-Client。stdio 桥接会自动处理。

本地 stdio 接入

网关服务必须已经运行。桥接进程只连接网关，全部下游 MCP 仍由同一个网关运行时管理。

以下三个命令完全等价，客户端 JSON 的 command 也可任选其中一个：

mmg stdio --url http://127.0.0.1:8765
mcp-manager stdio --url http://127.0.0.1:8765
mcp-manager-gateway stdio --url http://127.0.0.1:8765

Windows PowerShell：

$env:MCP_MANAGER_TOKEN = "mcpm_你的Token"
mcp-manager stdio --url http://127.0.0.1:8765

Linux：

MCP_MANAGER_TOKEN=mcpm_你的Token mcp-manager stdio --url http://127.0.0.1:8765

也支持 --token 参数；URL 可通过 MCP_MANAGER_URL 设置。客户端的通用 JSON 配置：

{
  "mcpServers": {
    "mcp-manager": {
      "command": "mcp-manager",
      "args": ["stdio", "--url", "http://127.0.0.1:8765"],
      "env": {"MCP_MANAGER_TOKEN": "mcpm_你的Token"}
    }
  }
}

个人中心提供可复制的 HTTP、stdio、Codex 及通用客户端配置示例。

生命周期

• lazy：首次工具调用启动；同一共享范围的并发调用只创建一个实例。
• eager：服务共享实例在启动时预热；已有授权的个人 OAuth 按用户预热。其他用户/会话隔离实例需要对应身份首次接入后建立。会话隔离实例在最后引用释放后关闭。
• disabled：不进入可用工具目录，也不接受业务调用。
• 手动停止会设置临时停止状态，直到显式启动或保存新的启用策略。
• 公共服务共享实例；个人 OAuth 按用户隔离；其他有状态服务可选服务、用户、会话隔离。
• stdio 桥接有独立租约，每 30 秒心跳、90 秒失联到期，正常退出主动释放。心跳异常或连接失效后，在下一次新请求前重建连接，已经派发的业务调用不会重放。
• 支持 MCP 会话的 HTTP 客户端可用 DELETE 释放；未报告退出的通用 HTTP 客户端采用保留租约。
• 只有所有引用释放后，按需实例才停止。默认 24 小时没有业务调用也会回收；心跳和目录刷新不算业务调用。活动调用不会被空闲回收杀死。系统设置中的空闲回收时间设为 0 时，关闭业务空闲超时回收；主动断开和桥接失联租约仍正常释放。
• 单实例并发、排队、启动、调用与停止超时可配置；停止和配置换代会阻止继续派发排队请求。
• 发送后失去结果标记为 outcome_unknown，不自动重放调用。

Windows 使用 MCP SDK 的 Job Object 清理子进程树；Linux 使用独立进程组。Linux 作为长期服务运行时，建议使用附带的 systemd 单元（KillMode=control-group）或 Docker init，以在网关异常终止时一起回收进程。

OAuth

在 MCP 认证配置中选择 oauth，填写 authorization_url、token_url、client_id、client_secret（可选）和 scopes。scopes 是 OAuth 权限列表（例如 mcp:read）；网关的 scope 固定为 user，每位用户独立授权。支持授权码、PKCE、一次性 state、Token 刷新及 client_secret_post/client_secret_basic。

回调地址为 PUBLIC_URL/api/v1/oauth/callback。用户在个人中心或 MCP 服务授权入口完成自己的授权；访问令牌调用时使用令牌所属用户的 OAuth 凭据。凭据、能力目录和运行实例按用户隔离。旧配置中省略 scope 或设置 service 的 OAuth 也按用户隔离运行，旧共享凭据不会复用，各用户需重新授权。断开或授权失效仅影响本人。

调用日志默认对管理员展示全部用户，可按用户名或用户 ID 搜索筛选；普通用户的列表、详情和导出始终限于本人。

数据和迁移

默认配置：

DATABASE_URL=sqlite://mcp-manager.sqlite
# 或
DATABASE_URL=mysql://user:password@host:3306/dbname?charset=utf8mb4

MySQL 数据库需要提前创建；系统自动执行表结构升级。SQLite 相对路径以 DATA_DIR 为基准，DATA_DIR 默认是用户配置目录，也支持 Windows/Linux 绝对路径。URL 中密码的特殊字符需要 URL 编码。

目录（可由 MCP_MANAGER_HOME / DATA_DIR 覆盖）：

日志保留天数默认为 0（无限保留）。设为 7 时，后台自动清理超过 7 天的调用日志原文和查询索引；保存设置后在下一轮维护中检查（通常 5 秒内），之后每小时检查。审计日志独立保留。

个人资料的登录会话显示登录 IP 和设备 UA，支持撤销或彻底删除其他登录会话；旧会话未采集的信息显示为未知。

系统设置的关于页面提供安装版本、项目主页、发布地址、Issue 反馈和作者主页。

备份时保留用户目录内的 .env、整个 DATA_DIR 及系统数据库；SECRET_KEY 或 secret.key 必须保留，否则原凭据无法解密。

旧版源码目录数据可以离线复制到一个空用户目录（原目录保留）：

mcp-manager --home ~/.mcp-manager migrate-home --from-data /旧项目/data

旧版本有 .env 时同时传入 --from-env /旧项目/.env。命令保留有效密钥，检查 SQLite 完整性；源实例运行中、目标非空或配置文件不存在时拒绝迁移。也可以在完全停止网关后，将整个旧 data 目录直接剪切为新的用户目录，必须保留 secret.key 与日志等配套文件。

停止网关后迁移到一个空目标数据库：

mcp-manager migrate-db --target-database-url "mysql://user:password@host:3306/newdb?charset=utf8mb4"

也支持 MySQL → SQLite。迁移保留用户、Token、授权、系统设置、配置和 OAuth 密文；日志与能力缓存继续使用原 DATA_DIR。完成后修改 DATABASE_URL 再启动。目标有业务数据时拒绝覆盖。

仅升级表结构：mcp-manager upgrade。 停止网关后离线重建日志索引：mcp-manager rebuild-logs；运行中可在日志管理执行重建任务。

Docker / Linux 服务

docker compose up --build -d

Compose 使用单个网关进程，数据持久化到命名卷 mcp-manager-data，容器内用户目录为 /data。需要宿主机目录时，将挂载项替换为 /你的持久化目录:/data。生产镜像安装构建出的 wheel，不依赖源码 checkout。容器内配置的 stdio 命令必须安装在容器中；Node 等额外运行时需要在派生镜像中安装。访问其他容器的服务应使用其容器网络地址。

构建环境无法访问 PyPI 时，可通过 docker build --build-arg UV_DEFAULT_INDEX=https://你的镜像/simple --target production -t mcp-manager . 指定 Python 包索引；默认仍使用 PyPI。

原生 Linux 服务运行时，网关自身会管理 Windows/Linux 子进程清理（Job Object / 进程组）。每个部署只运行一个网关实例，不使用多 worker 或多副本共享进程调度。

开发

后端为 src/mcp_manager 下的独立模块；包内 static/ 为原生 JS ES 模块，通过 /api/v1 与后端通信。迁移脚本在包内 migrations/，测试在 tests/，生成的截图和验收产物在 artifacts/。前端可单独部署，由同源反向代理转发 /api、/gateway 和 /mcp。

uv sync --frozen --group dev
uv run mcp-manager serve
uv run pytest tests -q
node --test tests/frontend/core.test.mjs
uv build

浏览器测试需要本机 Chrome 或 Playwright Chromium。MySQL 专项测试通过 MCP_TEST_MYSQL_URL 指向专用的空测试数据库。API 文档在 /docs。

传输插件使用 Python entry point 组 mcp_manager.transports；实现 validate(config) 和异步上下文 connect(spec)，连接对象提供 discover()、call(name, arguments)，可选 read_resource/get_prompt。网关统一处理授权、租约、并发、日志和关闭。插件接口说明见 docs/plugins.md。

本版的部署边界是单节点、单运行时。自定义下游进程可以执行操作系统命令，MCP 配置权限属于管理员；为不同信任域配置不同运行账户或隔离容器。