暖飞机
Warmplane 是保持MCP会话温暖的本地控制平面。
它在一个本地进程后面运行多个上游MCP服务器,保持这些会话的持久性,并为工具/资源/提示提供一个紧凑的交互界面。目标是具体和可衡量的:减少启动延迟,减少有效载荷大小,并保持行为确定性。
为什么存在
大多数代理堆栈通过急切地展示从未使用过的大型工具目录和详细模式,在令牌和延迟方面付出了过高的代价。
Warmplane 将该模型转换为懒惰、紧凑的交互:
- 首先发现紧凑型索引。
- 仅在需要时获取详细信息。
- 通过标准化信封执行。
这改善了:
- 代币效率
- 首次有用工具调用时间
- 跨客户端一致性
- 可观测性与策略控制
它提供了什么
一个运行时,三种访问模式:
- HTTP外观(
/v1/...) - CLI外观命令
- MCP外观服务器模式(
mcp-server)适用于MCP本地客户端
所有三种模式共享相同的后端状态、别名、策略检查和超时行为。
核心立面表面
能力
- 列表:紧凑型能力指数
- describe:一种功能的按需详细信息
- 调用:规范化执行信封
资源
- 列表:紧凑资源索引
- read:标准化读取信封
提示
- 列表:紧凑提示索引
- get:规范化的提示渲染封套
安装
cargo install --path .cargo install warmplane 还不可用,因为crate尚未发布到crates.io。
验证配置
启动前验证和整理配置:
warmplane validate-config --config mcp_servers.json成功输出示例:
{"ok":true,"config":"mcp_servers.json","servers":3}配置
创建 mcp_servers.json:
{
"port": 9090,
"toolTimeoutMs": 15000,
"capabilityAliases": {
"sqlite.read_query": "db.query"
},
"resourceAliases": {
"filesystem.file:///tmp/readme.txt": "fs.readme"
},
"promptAliases": {
"github.code_review": "prompt.code-review"
},
"policy": {
"allow": ["db.*", "fs.*", "prompt.*"],
"deny": ["fs.secret"],
"redactKeys": ["token", "api_key", "password"]
},
"mcpServers": {
"sqlite": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sqlite", "./test.db"]
},
"remote_docs": {
"url": "https://mcp.example.com/mcp",
"protocolVersion": "2025-11-25",
"allowStateless": false,
"headers": {
"X-Tenant": "acme"
},
"auth": {
"type": "bearer",
"tokenEnv": "REMOTE_DOCS_MCP_TOKEN"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}每 mcpServers.,运输选择是严格和推断的:
- stdio上游:设置
command(加可选args,env) - HTTP/SSE上游:设置
url(加可选protocolVersion,allowStateless,headers,auth) - 正好是其中之一
command或url必须设置
不支持旧配置回退。
HTTP身份验证
auth.type = "bearer":
{
"type": "bearer",
"tokenEnv": "MCP_TOKEN"
}auth.type = "basic":
{
"type": "basic",
"username": "svc-user",
"passwordEnv": "MCP_PASSWORD"
}对于承载者/基本用户,只有一个直接的秘密(token/password)或env支持的秘密(tokenEnv/passwordEnv)是必需的。
运行模式
1) HTTP守护程序
warmplane daemon --config mcp_servers.json终点:
GET /v1/capabilitiesGET /v1/capabilities/:idPOST /v1/tools/callGET /v1/resourcesPOST /v1/resources/readGET /v1/promptsPOST /v1/prompts/get
2) MCP服务器(stdio)
warmplane mcp-server --config mcp_servers.jsonMCP客户端可以直接指向此进程。
暴露的合成轻质工具:
capabilities_listcapability_describecapability_callresources_listresource_readprompts_listprompt_get
还支持本机MCP方法:
- 资源:
resources/list,resources/read - 提示:
prompts/list,prompts/get
3) CLI外观
# capabilities
warmplane list-capabilities
warmplane describe-capability db.query
warmplane call-capability db.query --params '{"query":"SELECT 1"}'
# resources
warmplane list-resources
warmplane read-resource fs.readme
# prompts
warmplane list-prompts
warmplane get-prompt prompt.code-review --arguments '{"code":"fn main() {}"}'MCP客户端示例
{
"mcpServers": {
"fast-facade": {
"command": "warmplane",
"args": ["mcp-server", "--config", "mcp_servers.json"]
}
}
}冒烟测试
运行端到端stdio MCP烟雾测试:
./scripts/smoke_mcp_server.sh它验证了:
- 主控程序
initialize tools/list包括所有合成轻质外墙工具resources/list和prompts/list返回有效响应
设计说明
- 上游MCP兼容性保持不变。
- 面向客户端的模式有意地小而稳定。
- 策略和别名在不同模式下得到一致执行。
- 对于确定性编排,超时和错误包络是标准化的。
- 运行时日志是结构化的JSON,用于可审计性。
- 通过OTLP支持OpenTetry跟踪导出。
可观测性
默认情况下,Warmplane会发出结构化的JSON日志(tracing + tracing-subscriber).
示例控件:
RUST_LOG=info,warmplane=debug设定冗长WARMPLANE_OTEL_ENABLED=true启用OpenTetry导出OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317设置OTLP收集器终结点WARMPLANE_OTEL_ENDPOINT=http://127.0.0.1:4317如果出现以下情况,则回退OTLP端点OTEL_EXPORTER_OTLP_ENDPOINT未设置WARMPLANE_SERVICE_NAME=warmplane-prod覆盖服务名称
操作说明:
- 日志包括用于审计跟踪的结构化请求/能力/资源/提示字段。
trace_id执行中的信封可以与日志和分布式跟踪相关联。- 启用OTEL后,跟踪将通过OTLP-gRPC导出,本地结构化日志将保持活动状态。
有关详细的请求/响应合同,请参阅 docs/spec.md.
其他参考文献:
- OpenAPI: openapi.yaml
- 配置架构: config.schema.json
- 安装/分发: 安装.md
- 部署运行手册: 部署.md
- 可观察性: 可维护性.md
