ramen

用 Python 构建 MCP 工具，并将其部署到 GKE、EKS 和 AKS 的各个区域。
Rust MCP 节点 + Python 3.12 运行时工作进程，边缘使用 Streamable HTTP，内部使用 gRPC，为每个工具设置防护措施，
通过 Entra ID 和 Google Workspace 登录，支持自动扩缩容——统一由一个 FastAPI 控制台管理。

文档：https://bkraad47.github.io/ramen/ · 开始使用 · 工作原理 · MCP 仓库 · 使用 OAuth 连接客户端 · 在 GCP 上部署 · AWS · Azure · 契约 · 发行版

Streamable HTTP 是对外入口。 每个工作进程都提供 POST /mcp——只需一个 URL 和一个 bearer 标头，无需 安装——同时还提供从 0.3.1 版本起便已支持的 gRPC 服务；二者使用相同端口，并经过相同的防护措施。对于只支持 stdio 的客户端，仍可使用 stdio 桥接器。

状态。 当前发行版为 0.8.0，已于 2026-10-17 在 GKE、EKS 和 AKS 上完成实时验证——每个云平台均执行了 smoke 测试、包含 63 项检查的发行版测试套件以及六种负载测试场景——随后已拆除；CI 在 Linux 和 Windows 上验证这两种传输方式。每次运行覆盖内容及仅经过测试的内容，都记录在 传输方式 → 验证内容中。

跨区域构建并部署自己的 MCP 工具。 Ramen 将一个包含工具、资源和提示词的 Git 仓库 转化为部署在云负载均衡器之后的一组 MCP 工作进程，并在一个控制台中统一管理调用权限、密钥、防护措施、金丝雀发布门控和审计记录。这是一个供你构建自己工具的平台，而不是一个代理其他人服务的网关。每个工作进程由一个 Rust MCP 节点（在同一端口上提供 Streamable HTTP 和 gRPC、bearer 身份验证、IP 允许列表、健康状态和日志）与一个 Python 3.12 运行时组成，后者通过 pip 安装并运行你的代码：用户代码绝不会在持有密钥的进程中运行。有关架构、数据模型以及各组件如此安排的原因，请参阅： 工作原理。

• Git → 存储桶 → worker。 部署会将仓库同步到存储桶；worker 按内容哈希加载。Pod 中不存放 Git 凭据。
• 默认采用金丝雀发布，并设有门禁。 部署金丝雀版本，对 tools/list 进行冒烟测试，将其工具架构与稳定版本进行比对（除非你设置 breaking: true，否则会阻止破坏性变更），运行仓库的黄金用例，然后发布稳定版本。失败时，稳定版本不受影响。
• 从第一天起支持多可用区。 Group → Environment → Zone → Worker；负载均衡器根据 ramen-group / ramen-zone 进行路由，因此一份客户端配置即可适用于所有可用区。
• 在 worker 内设置护栏。 可选择让工具在调用前和结果返回后进行检查；检查与工具一起在 Python 运行时中执行：使用 NVIDIA NeMo Guardrails 护栏（确定性护栏或由 LLM 提供支持的护栏，可使用你自己的模型和密钥），或使用你自己编写的 policy.py。被拦截的调用会返回易读的工具错误，访问日志会标明所用护栏。默认失败时拒绝访问。
• 由你的身份提供商做出决定，管理员可手动覆盖。 在任意云上的 Config 页面添加 Microsoft Entra ID、Google Workspace 或任何 OIDC 提供商；在登录时通过 Graph 或 Cloud Identity 读取用户所属的组，为每个 group 将其映射到相应角色，并保留管理员手动设置的内容。
• 每个 group 可设置角色，也可自定义角色。 可使用 Group Admin、Viewer、MCP User，或基于上述角色自定义角色（例如基于 Viewer 的 analyst）；这些角色可用于成员资格、提供商规则和逐工具访问控制；角色还可以是仅限 OAuth。可按环境决定谁可以查看和调用每个工具；漂移信号会标记重复调用同一工具的调用者。
• 由 Ramen 自动扩缩容。 每个可用区运行 1 个到管理员设定的最大数量的 worker；控制台会在负载增加时快速扩容，在空闲时缩容，三个云上的行为一致，无需 HPA，且每一步都会记录在审计日志中。
• 支持三种云。 为 GKE、EKS 和 AKS 提供 Terraform 和 Helm；三个云上使用相同的控制台和护栏（部署到云端）。
• 企业级控制。 rmk_ MCP 密钥和 rmn_ API 密钥均以加盐哈希形式存储；可在节点层和云边缘按可用区设置 IP 规则；密钥永不显示；支持 Redis 限流，每项操作都会生成一条审计记录。
• 每个可用区部署一个 Deployment，而非每个工具部署一个。 worker 会加载该 group 的所有工具，因此 30 个工具可在每个可用区的一个 Deployment 上运行（使用金丝雀时有两个 Pod），并由一个负载均衡器提供服务；自动扩缩容会根据负载增加 Pod，而非根据工具数量扩容。

从这里开始 · 演示 group 仓库 ramen-demo-mcp-group （将 group 指向该仓库并按下 Deploy）· stdio 桥接工具 ramen-mcp-bridge on PyPI （uvx ramen-mcp-bridge@latest）· Docker Hub 和 GHCR 上的镜像 bkraad47/ramen-worker 和 bkraad47/ramen-console。

快速入门（本地，5 条命令）

需要安装带 compose v2 的 Docker、uv、git 和 make。make up 会从 Docker Hub 拉取该版本的两个镜像，大约需要一分钟；make up BUILD=1 则会从源代码构建镜像，需要三到五分钟。

git clone https://github.com/bkraad47/ramen && cd ramen
make up       # Firestore emulator + console https://localhost:8443 + one worker (localhost:8080: Streamable HTTP + gRPC)
make demo     # zone, group `demo` from the demo repo, an rmk_ key, a canary deploy, then a tools/call
#   PASS: demo_calculator_tool(2,3,add) -> 5      <- the success line
open https://localhost:8443    # self-signed cert; [email protected] + the generated password: grep ADMIN_PASSWORD deploy/local/.env
make down     # stop and remove volumes

make demo 可安全地重复运行：如果可用区、group 或环境已存在，命令会提示“exists”，并且每次都会生成新的密钥。堆栈中没有任何静态密钥：make up 会将管理员密码、Fernet 密钥、MCP 密钥、管理员密钥和会话密钥写入 deploy/local/.env（已被 git 忽略），而且如果有任何明文密钥再次出现，scripts/check_secrets.py 会使 CI 检查失败。

连接客户端

worker 是一个 URL（/mcp）和两个路由请求头：ramen-group 和 ramen-zone。凭证决定调用以谁的名义运行：

• 组密钥（rmk_），放在 Authorization: Bearer 中，适用于 Agent 和自动化场景。适用于任何支持 HTTP 的客户端。
• 个人登录，通过控制台登录（OAuth 2.1，可使用 Ramen 密码、Entra ID 或 Google）：通过 HTTP 使用 Claude Code，或通过桥接程序使用任何 stdio 客户端。

所有连接方式及对应页面： 开始使用 → 连接客户端 · 通过 OAuth 连接 · 传输 → 连接。在云环境中，组页面上的 MCP 用户如何登录卡片会显示适用于你安装方式的准确命令。

截图

登录	仪表板，按区域和组显示负载

组：环境、部署作业、区域/worker、MCP 密钥	部署作业及实时日志

密钥（仅显示名称，绝不显示值）	日志（每次 MCP 调用对应一行 JSON，可下载）

身份提供商：Entra ID，支持组查询和角色规则	自定义角色，其中一个仅限 OAuth

区域操作：数量上限、最大值、上次自动扩缩决策	区域和 worker，以及每个组的最大值

传输与安全，简述

worker 通过一个端口提供 Streamable HTTP（POST /mcp，MCP 规范 2025-06-18）和 gRPC（ramen.v1.Mcp/Call），并通过同一套防护实现进行处理，因此检查要么同时应用于两种传输方式，要么都不应用。TLS 在负载均衡器处终止。节点会检查凭证、来自提供商 x-forwarded-for 跳点的来源范围、被屏蔽的名称，以及大小和并发上限。运行时使用区域自己的云身份访问存储桶，防护措施则在运行时与工具之间执行。逐跳说明各环节的保护措施及验证内容： 传输。边界与非目标： 威胁模型。

部署到云端

目标	Terraform 和 Helm 构建的内容	指南
GCP	GKE Autopilot、Firestore、GCS、Secret Manager、全局 HTTPS LB（GKE Gateway，基于请求头路由的 gRPC 和 Streamable HTTP）、Cloud Armor	文档 · deploy/README.md
AWS	EKS、DynamoDB、S3、Secrets Manager、ALB（gRPC 和 HTTP/1.1 目标组）、WAF（Terraform 或 CloudFormation）	文档
Azure	AKS（工作负载身份）、Table Storage、Blob Storage、Key Vault、使用 Let's Encrypt 证书的 Envoy Gateway	文档
本地	docker compose：Firestore 模拟器、控制台、一个 worker；每次推送都会运行 CI 端到端测试	deploy/local/README.md

每种环境的启动步骤都相同：terraform apply → helm upgrade --install（使用该版本的公共镜像，或运行 make push 推送到你自己的镜像仓库）→ 在控制台中添加区域和组 → 部署。大约需要 25 分钟，主要时间花在等待集群和负载均衡器就绪。边缘节点会在免费的 sslip.io 主机名上获取公开可信的证书 （AKS 使用 Let's Encrypt），因此客户端使用 https://<public_hostname>/mcp，桥接程序则指向 <public_hostname>:443 --tls，无需导入任何内容。各云部署运行涵盖的内容： 传输 → 验证内容。

编写自己的工具

群组仓库是指包含 mcp/tools/<name>/<name>.py 和 <name>.json（以及 resources/、prompts/、requirements.txt）的任意 git 仓库。密钥通过 {{$group.NAME}} 引用，或通过 mcp/env.yaml 导出；传输层的任何信息都不会泄露到工具代码中。声明 output，工作进程会将其发布为 outputSchema，并校验每个结果；添加 mcp/tests.yaml，其中的测试用例会作为每次部署的门禁；添加 mcp/guardrails.yaml，NeMo 护栏或 policy.py 会在工具运行前检查参数，并在结果离开工作进程前进行检查。从 ramen-demo-mcp-group 开始；有关契约、本地开发和重量级依赖，请参阅：MCP 仓库 · 护栏。

仓库

目录	内容
console/	FastAPI + Jinja2 + HTMX 管理界面和 /api/v1；连接工作进程的 gRPC 客户端
node-rs/	Rust MCP 服务节点（tonic：ramen.v1.Mcp、ramen.v1.Admin、grpc.health.v1.Health；认证、CIDR、sidecar 监管器）
runtime-py/	Python 3.12 运行时（加载 proto、通过 pip 安装、运行调用、解析密钥、运行护栏）
proto/	ramen/v1/mcp.proto、admin.proto — 传输契约，是 Rust 和 Python 存根的唯一来源
deploy/	compose、Helm 图表、Terraform（GCP、AWS、Azure）、CloudFormation
glama/、mcpb/	独立目录镜像和 Smithery 包；两者都固定桥接版本
skills/	云运维 Agent 技能：deploy-gcp、deploy-aws、rotate-keys、backup-restore、scale-zone
tests/	黑盒一致性测试（gRPC + 桥接）、端到端测试和云测试套件
docs/	本网站的源文件；docs/CONTRACTS.md 对每个组件都具有约束力（§11 = 传输层）

架构：ARCHITECTURE.md · 变更：CHANGELOG.md · 版本：跟踪器 · 版本之间的对应关系：发行版

开发

make up BUILD=1      # the compose stack from source instead of the published images
make test            # runtime-py and console (pytest, 90% coverage gate) plus node-rs (fmt, clippy, test)
make test-harness    # tests/: conformance + e2e (skips without a running stack)
make proto           # regenerate Python stubs from proto/ (Rust stubs build via tonic-build)
make demo-worker     # node + runtime locally without Docker
uv run --project docs --group docs mkdocs serve   # docs at http://127.0.0.1:8000

贡献

请参阅 CONTRIBUTING.md — 使用、派生并修改它，同时注明出处；将其改名为自己的新商业产品不可接受。

许可证

BSD-3-Clause © 2026 Raad。请参阅 LICENSE。