mcprack

mcprack <div align="center">  **模型上下文协议（MCP）自助服务目录和配置生成器**        </div> mcprack 是一个用于在组织中管理和分发 MCP（模型上下文协议）服务器配置的集中式平台。它解决了如何为 AI 客户端（如 Claude Desktop、GitHub Copilot 等）安全地提供对多个后端服务的访问权限，而无需在每台机器上进行硬编码或手动配置。  ## mcprack 的功能 ### 问题 您有多个 MCP 服务器（将 AI 客户端连接到您的服务：数据库、API、知识库等）。您希望用户： - 轻松发现可用的服务器 - 自助选择他们需要的服务器 - 获取适用于其客户端的即用配置文件 - 在不访问原始机密的情况下安全地管理凭证 ### 解决方案 mcprack 提供： 1. **管理员界面** — 注册 MCP 服务器，定义环境变量和默认值，将机密存储在 Vaultwarden 中 2. **用户目录** — 浏览可用的服务器，选择需要的服务器，选择目标客户端（Claude、Copilot 等） 3. **配置生成器** — 自动为每个用户生成适用于其所选服务器的 `.json` 或 `.env` 配置文件 4. **凭证管理** — 凭证从未存储在 mcprack 的数据库中；每个机密都存储在 Vaultwarden 中（可选地，每个用户可以覆盖） 5. **HTTP 代理** （可选）— 通过 HTTP 暴露基于 stdio 的 MCP 服务器，以便远程客户端可以访问它们 ### 典型工作流程 1. **管理员** 注册一个新服务器（例如，`mastodon-mcp`）： - 命令：`/usr/bin/mastodon-mcp` - 环境变量：`MASTODON_INSTANCE`，`MASTODON_ACCESS_TOKEN` - 在 Vaultwarden 安全笔记中保存默认值：`MCP-mastodon-mcp` 2. **用户** 登录到 mcprack（本地帐户或 Active Directory）： - 在目录中查看可用的服务器 - 选择他们需要的服务器：✓ mastodon-mcp，✓ postgres-mcp - 选择目标：“Claude Desktop” - 下载带有这些服务器的 `claude_desktop_config.json` 3. **AI 客户端** （Claude）加载配置： - 启动每个选定的 MCP 服务器作为子进程 - 现在可以调用函数和访问所有这些后端工具 凭证从未暴露给用户或不安全地存储；它们在运行时来自 Vaultwarden。 --- ## 认证 **本地帐户** 始终可用。 **LDAP/Active Directory** 是可选的，默认情况下是禁用的 — 如果您希望用户使用 AD 凭证进行身份验证，请在安装时启用它。 ## 主要功能 - **Vaultwarden 中的机密，数据库中的纯配置** — 只有管理员标记为“citlivé”（敏感）的数值（API 密钥、令牌、密码）才会进入 Vaultwarden；其他所有内容都直接存储在 mcprack 的数据库中，无需 Vaultwarden 往返 - **用户级凭证覆盖** — 用户可以可选地为任何服务器提供自己的凭证（存储在 Vaultwarden 中为 `MCP-<server>-user-<username>`，或在未配置 Vaultwarden 时本地加密） - **多客户端支持** — 为 Claude Desktop、GitHub Copilot 和其他 MCP 兼容客户端生成配置 - **管理员配置交接** — 管理员可以查看和下载任何用户的客户端配置，从管理员 → 用户，用户自己从未登录到 Web UI - **每用户代理** — 每个用户远程连接；stdio 服务器按需启动，每个（用户，服务器）对的隔离实例，启动时解析凭证 — 永远不会嵌入到下载的配置中 - **Vaultwarden 集成** — 利用与 `mcp_rack` Ansible 角色相同的 `bw-cli` / 安全笔记模式 - **无需 Vaultwarden 即可工作** — 如果未配置，敏感值将退回到本地 Fernet 加密列；管理员可以有意地在管理员 → Vaultwarden 诊断之间进行迁移 - **LDAP/AD 支持** — 企业部署的可选目录身份验证 ## 架构  **组件：** - **Flask 应用**：核心 Web 服务，处理身份验证、服务器管理、配置生成和每用户代理 - **数据库**：服务器注册、用户、选择和非机密服务器配置（SQLite、PostgreSQL 或 MySQL） - **Vaultwarden**：仅存储敏感凭证（当配置时）- 参见 `secret_store.py` - **本地加密备用**：在未配置 Vaultwarden 时使用；从未同时用于同一值 ## 用例 **场景 1：具有共享 MCP 服务器的团队** - 您的团队已为 PostgreSQL、内部 API、Slack、Jira 等构建了 MCP 服务器 - 开发者在其自己的机器上使用 Claude Desktop 或 GitHub Copilot - 他们根据角色需要访问这些服务器的不同子集 - 解决方案：部署 mcprack 一次，注册每个服务器，让用户自助其配置 **场景 2：企业部署** - 多个团队，每个团队具有不同的访问控制 - 需要与 Active Directory 集成以实现 SSO - 在 Vaultwarden 中集中管理凭证 - 解决方案：启用 LDAP 的 mcprack，按团队配置服务器 **场景 3：远程团队** - MCP 服务器托管在内部网络上 - 不同网络/VPN 上的用户需要访问它们 - 解决方案：这是默认模式和唯一模式 — 每个用户都通过 mcprack 的内置每用户代理远程连接，无需部署额外的服务 **场景 4：多客户端支持** - 一些用户更喜欢 Claude Desktop，其他用户使用 GitHub Copilot - 不同的客户端具有不同的配置格式 - 解决方案：mcprack 自动生成特定于客户端的配置 ## 认证 **本地帐户** 始终可用。 **LDAP/Active Directory** 是可选的，默认情况下是禁用的 — 如果您希望用户使用 AD 凭证进行身份验证，请在安装时启用它。 ## 快速入门（开发） ```bash python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt -r requirements-dev.txt cp .env.example .env # 根据需要编辑 export $(grep -v '^#' .env | xargs) flask db upgrade flask create-admin flask run ``` 打开 http://127.0.0.1:5000，登录您刚刚创建的管理员帐户， 在 **服务器** 下注册一个服务器，然后访问目录以选择它并 下载配置文件。 ## 数据库 `SQLALCHEMY_DATABASE_URI` 默认使用 SQLite，但 PostgreSQL （`postgresql+psycopg2://...`，需要 `psycopg2-binary` / `python3-psycopg2`）和 MySQL（`mysql+pymysql://...`，需要 `PyMySQL` / `python3-pymysql`）都有效 - 参见 `requirements-db.txt`。 ## 凭证（Vaultwarden） 在服务器编辑表单中，每行环境变量都有一个“citlivé”（敏感）复选框。只有标记为敏感的行 — API 密钥、令牌、 密码和 HTTP 身份验证令牌密钥（始终强制敏感）— 才会离开 mcprack 自己的数据库。非敏感配置（基本 URL、区域、 日志级别...）直接存储在数据库中，永远不会接触 Vaultwarden。 敏感值（服务器的默认值和用户设置的任何个人覆盖） 存储在 Vaultwarden 中 - 当配置了 Vaultwarden 时，mcprack 与 `mcp_rack` Ansible 角色（`bw-cli`，名为 `MCP-<server-name>` 的安全笔记）/ `MCP-<server-name>-user-<username>`，纯 `KEY=value` 行）以相同的方式进行交互。*当 Vaultwarden 已配置时*。如果 `BW_SERVER` 未设置，则相同敏感 值存储在本地 Fernet 加密列中，由 `SECRET_KEY` 导出的子密钥索引。哪个后端是权威的，完全由配置决定，永远不会由实时可达性决定 - 无法访问但已配置的 Vaultwarden 是一个硬错误，而不是静默的备用。管理员可以 有意地在两个之间移动数据，从管理员 → Vaultwarden 诊断 （例如，在第一次配置 Vaultwarden 之后，或在计划的 Vaultwarden 停机之前）。 ### 1. 从 Vaultwarden 获取 API 密钥 1. 登录到您要 mcprack 使用的 Vaultwarden 网络保险库（例如， `https://vaultwarden-dev.proxy.spojenet.cz`）。 2. 进入 **帐户设置 → 安全 → 密钥** （或 **API 密钥**）并 生成/查看 API 密钥。注意 **client_id**、**client_secret** 和 您的帐户的 **master password** — 这三个加上服务器 URL 就是 mcprack 所需的一切。 ### 2. 设置连接变量 在环境中设置以下四个（以及可选的 `BW_ITEM_PREFIX`，默认为 `MCP-`）— 本地开发使用 `.env`，生产环境使用 `/etc/mcprack/env`（参见 `debian/README.Debian`）： ```bash BW_SERVER=https://vaultwarden-dev.proxy.spojenet.cz BW_CLIENTID=user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx BW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx BW_PASSWORD=your-vaultwarden-account-master-password ``` `BW_BIN`（默认为 `/usr/bin/bw`）和 `BITWARDENCLI_APPDATA_DIR`（`bw` 存储其登录/会话状态的位置）很少需要更改其默认值。 ### 3. 验证连接 以管理员身份登录并在导航栏中打开 **Vaultwarden 诊断**（或 直接访问 `/admin/vaultwarden/wizard`）。它按顺序检查每个先决条件， 并在第一个失败步骤停止，并附有特定的修复方法，而不是简单地显示 `bw` 的原始错误文本。在编辑 `/etc/mcprack/env` 和重启 `mcprack.service` 以加载更新的环境后重新运行它。 一旦每个步骤都是绿色的，管理员就可以保存服务器凭证 直接写入 `MCP-<server-name>` 安全笔记），用户可以下载/查看配置文件（它们会读取这些笔记并合并任何个人覆盖）。 ## 审计日志 mcprack 保留一个只追加的审计跟踪，以便可以追溯问题（损坏的服务器、凭证问题、意外的代理）到哪个 MCP 服务器和哪个用户引起了它。**它始终开启** — 没有 启用/禁用标志，因为这是安全功能，而不是可选的便利。 ### 记录内容 每个事件记录：时间戳（UTC），执行用户（如果有 - 有些事件 是由系统发起的，例如空闲代理清理），涉及的 MCP 服务器，操作， 操作是否成功，失败时的短错误代码/消息，客户端的源 IP/主机名，耗时，以及一个 `request_id` UUID，用于关联单个传入请求（例如凭证查找和代理启动）的多个事件。 当前记录的事件： - `login` / `login_failed` — 每次登录尝试（``） - `config_download` —其客户端配置（`catalog.py`） - `credential_access` — 服务器的机密从 Vaultwarden 解决（`vaultwarden.py`）- 记录 * 发生，永远不会是值 - `proxy_start` / `proxy_stop` — 一个用户 FastMCP 代理实例启动， 被管理员停止或因空闲而回收（`user`） - `admin_change` — 管理员操作：服务器/用户创建/编辑/删除和审计 存档运行本身（`admin.py`，`flask audit-archive`） ### 未记录的内容 请求的或响应的正文，工具调用参数/结果和凭证 值永远不会写入审计日志 — 只有发生访问或 调用的事实。`error_message` 始终是一个短的固定字符串， 从不包含原始请求内容。 ### 查看审计日志 管理员可以在 **管理员 → 审计日志** （`/admin/audit-log`）中浏览审计跟踪，按服务器、用户、时间窗口和 仅错误进行筛选。单击某行中的链接以查看共享其 `request_id` 的所有事件。无法从 UI 编辑或删除单个条目 — 审计日志按设计只允许追加。 ### 保留和存档 `AUDIT_RETENTION_DAYS`（默认为 `90`）控制保留条目的时间长度。 没有任何内容会自动删除 — 定期运行 CLI 命令（例如，从 cron）以导出旧条目然后清除它们： ```bash flask audit-archive # 存档 AUDIT_RETENTION_DAYS 旧条目，导出为 JSON flask audit-archive --format csv # 导出为 CSV flask audit-archive --days 30 # 覆盖此运行的保留窗口 flask audit-archive --output /path/to.json flask audit-archive --dry-run # 仅报告将存档的条目数量 ``` 导出始终在内容之前进行，并且存档运行本身审计条目（谁/何时运行，删除了多少行）— 因此，即使清理旧行也会留下痕迹。 ## 可观察性（OpenTelemetry） mcprack 可以通过 OTLP 将分布式跟踪和到任何 自托管的 OpenTelemetry器（Grafana Alloy、香草 OTEL 收集器eger、Tempo ...）。与审计日志关于 内能够看到发生了什么 — 但与审计日志是 **按需开启**：当 `OTEL_ENABLED` 未设置/为，`telemetry.py` 是一个完整的 no-op（无跨度，无指标，无网络调用 不需要安装任何entelemetry-*。 ### 架构 ``` mcprack（Flask + SQLAlchemy + FastMCP） │ OTLP（ http/protobuf） ▼ OpenTelemetry / Grafana Alloy │ ├──▶ Jaeger / Tempo （跟踪） └──▶ Prometheus / Loki （指标） ``` ### 启用它 安装可选依赖项（`pip install -r requirements-otel.txt`， 或 `python3-opentelemetry-*` Debian 软件包 - 参见 `debian）， 然后设置： | 变量 | 默认 注释 | |---|---|---| | `OTEL_ENABLED` | `false` | 主开关。以下所有内容在关闭时均被忽略。 | | `OTEL_EXPORTER_OTLP_ENDPOINT` | *(空)* | 收集器的基本 URL，例如 `http://10.11.226:4318 | | `_SERVICE_NAME` | `mcprack `service.name属性。 | |EL_EXPORLP_PROTOCOL` | `http/protobuf`参见下表。 | | `OTACES_SAMPLER` | `parentbased_always_on` |/环境提示不验证自身| `OTEL_TRACE_UI_URL_TEMPLATE *(空)*审计日志条目上的“查看跟踪”链接的 URL - 参见。 | ### `OTELTER_OTLP 值 | 值？ | ---|---|---| http/protobuf` |默认）| 使用entelemetry-otlp-proto，通常为8`| `grpc` | 使用 `op-exporterto-grpc通常为端口`。`OTEL_EXPORTER_ENDPOINT` 中将原样使用cprack 重写它| `http/json ❌ | **** Python O SDK 与 JS，它不附带 JSON-over-HTTP器 - 仅-over-HTTP。设置此选项会记录启动警告，mcprack 透明地回退到/protobuf`；它因启动而| 其他 | ❌ | 与 `http/json` 具有相同的回退和警告行为。 | 检查 **管理员 → OTLP 诊断** （`/admin/otel/wizard`）以查看 有效的（回退后）协议，是否发生，以及 在配置的 URL 模板查看跟踪”链接 - 请文。 ### 示例 `.env`共享的 10.11.56.226 堆栈上进行测试 ```bash OTEL_ENABLED=trueEL_SERVICE_NAME=mcprack-demo OTEL_EXPORTER_OTLP_ENDPOINT10.11.56.226 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` 您也可以在本地eger 实例（带有 OTLP 接收器）， 这样您就可以在不接触共享查看端到端的跟踪： ```bash docker compose -f docker-compose.otel.yml up -d # 然后用 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost: 运行 mcprack # Jaeger UI: http://localhost:``` 添加 `--profile collector --profile grafana` 以同时获取， Prometheus 和一个配置的本地 Grafana 实例（`3001`， 匿名查看者访问）以尝试使用下面的板 - 参见顶部注释 `docker-compose.otel.yml` 以切的端口和 `OTEL_EXPORTER_OTLP_ENDPOINT` 在此模式下使用的值。 ### Grafana 仪表板 `grafana/mcprack-otel-dashboard.json` 是一个现成的仪表板， 了上面三个自定义指标：MCP 调用率（成功与错误按服务器划分的 p50/p95/p99 持续时间，按划分的配置文件下载， 以及一个搜索跟踪面板，限定在 mcprack 的服务名称范围内。 通过 **仪表板 → 导入** 在任何具有源的 Grafana 中导入它 由 OTLP 收集器的指标导出器提供（例如，共享的 `http://10.11.:3000`使用 `--profile grafana` 上面的本地实例）- 您将被提示选择该数据源 适用于 `${DS_PROMETHEUS}` （和 `${DS_TRACES}`，如果您的收集跟踪到那里）。 要直接从一个特定的审计日志条目跳转到其跟踪记录，而不是 浏览仪表板，请使用下面描述的“查看跟踪与 `audit.request_id` 相关的路径，而不是此仪表板。 ### 追踪内容 自动追踪：每个Flask请求/响应（通过`opentelemetry-instrumentation-flask`）和每个SQLAlchemy查询（通过`opentelemetry-instrumentation-sqlalchemy`）。 自定义跟踪范围，关注解决MCP问题的关键操作： - `mcp.server.call` — 通过用户专属代理转发到stdio MCP服务器的请求（`server_name`、`transport`属性） - `vaultwarden.lookup` — 读取Vaultwarden安全笔记（仅`secret_name_hash`属性 - 名称的单向哈希值，绝不会是名称或秘密值） - `catalog.generate_config` — 生成用于下载/查看的客户端配置 - `mcp.proxy.start` / `mcp.proxy.stop` — 用户专属FastMCP代理的生命周期 指标（OTEL Meter，而非仅限于追踪）： - `mcp_server_calls_total`（计数器；标签`server_name`、`result`） - `mcp_server_call_duration_seconds`（直方图；标签`server_name`） - `config_downloads_total`（计数器；标签`client_type`） **凭证和审计内容绝不会被追踪或纳入指标** — 遵循与审计日志相同的规则（参见上文）。追踪/指标属性仅限于标识符（服务器名称、哈希的秘密名称）、结果和持续时间；绝不会附加请求/响应正文或秘密值。 ### 将追踪与审计日志条目关联 审计轨迹已经为每个请求生成了一个UUID（`audit.py`、`flask.g`），以便将一次请求期间发生的所有操作联系起来。mcprack不会用该UUID覆盖OpenTelemetry自己的（由SDK生成的）追踪ID，而是将每个自定义跟踪范围标记为具有UUID作为`audit.request_id` **追踪属性**，因此您可以通过该属性查找追踪，而不是通过追踪ID。在审计日志的请求详情页面（`/admin/audit-log/request/<id>`）上，“查看追踪”按钮根据`OTEL_TRACE_UI_URL_TEMPLATE`构建链接，替换`{request_id}`（以及`{trace_id}`别名，以便模板更易读）—— 将其指向您的追踪UI中过滤该属性的已保存搜索/查询，例如对于使用TraceQL的Grafana/Tempo： ```bash OTEL_TRACE_UI_URL_TEMPLATE="http://10.11.56.226:3000/explore?left=%7B%22datasource%22:%22tempo%22,%22queries%22:%5B%7B%22query%22:%22%7B%20.audit.request_id%20%3D%20%5C%22{request_id}%5C%22%20%7D%22%7D%5D%7D" ``` 保持未设置状态，则按钮仅显示“未配置”，而不链接到任何位置。 ## 测试 ```bash pytest ``` ## 安装（Debian/Ubuntu 软件包） mcprack作为`.deb`文件发布在VitexSoftware APT仓库中。 ```bash sudo apt install lsb-release wget sudo wget -O /usr/share/keyrings/vitexsoftware.gpg https://repo.vitexsoftware.com/KEY.gpg sudo wget -O /etc/apt/sources.list.d/vitexsoftware.sources https://repo.vitexsoftware.com/vitexsoftware.sources sudo apt update sudo apt install mcprack ``` postinst向导通过`dbconfig-common`（SQLite、PostgreSQL或MySQL）设置数据库，写入`/etc/mcprack/env`，运行迁移，并创建初始的`admin`账户（随机密码保存在`/etc/mcprack/admin-credentials`中）。有关完整的安装后配置步骤，请参见`debian/README.Debian`，其他可用的软件包请参见[repo.vitexsoftware.com](https://repo.vitexsoftware.com/)。 ## 打包 参见`debian/` — 按照与其他VitexSoftware Flask应用（例如`abraflexi-yearend`）相同的约定构建`.deb`文件：系统Python包，无virtualenv，`gunicorn` + systemd。有关安装后的配置步骤，请参见`debian/README.Debian`。 ## 远程访问stdio MCP服务器 用户始终远程连接 — mcprack绝不会假设用户的Claude/Copilot客户端与mcprack本身运行在同一台机器上。因此，下载的配置始终指向用户专属的代理URL（`/proxy/mcp/<token>/<server_id>`），由`mcprack.service`本身提供 — 无需安装或启用单独的代理服务。 用户首次通过该URL连接其客户端时，mcprack会为该（用户，服务器）对按需启动专属的`fastmcp`子进程，并在那一刻解析该用户的凭证。每个用户都会获得自己的隔离实例，即使对于多个用户一次选择一个服务器；空闲实例会在15分钟后自动清理。这需要安装`python3-fastmcp`（`apt install python3-fastmcp`）— 有关正在运行的实例的实时列表，请参见管理 → 代理实例。 详见`debian/README.Debian`。 ## 品牌与图标 mcprack包含多个图标变体，以代表平台的五个功能区域： | 图标 | 用途 | 颜色 | |------|---------|--------| | `mcprack-app-icon.svg` | 应用启动器/图标 (256×256) | 2×2 网格： 蓝色（管理）/ 绿色（目录）/ 紫色（凭证库）/ 青色+橙色（注册/代理） | | `mcprack-icon-composite.svg` | 带有标签功能的中心图 | 环形设计，带有5个环绕功能环 | | `mcprack-badge.svg` | 文档的盾形徽章 | 重叠的彩色段 | | `mcprack-rings.svg` | 同心设计 | 环绕中心MCP中心的环 | | `mcprack-functions-bar.svg` | 网页头部/横幅 | 水平堆叠条，显示所有5个功能 | 所有图标均位于`static/`中，并包含在应用流元数据中，以便于应用目录发现。 **色彩方案：** - 🔵 蓝色 = 管理面板（管理和配置） - 🟢 绿色 = 用户目录（服务器选择） - 🟣 紫色 = Vaultwarden凭证库（凭证存储） - 🟠 橙色 = 服务器注册（库存） - 🔷 青色 = HTTP代理（远程访问）