Warmplane

The local control plane that keeps MCP sessions warm.
v0.7.0 — Changelog · User Guide · OpenAPI · Spec

Warmplane runs multiple upstream MCP servers behind one local process, keeps those sessions persistent, and exposes a compact, policy-aware surface for tools, resources, and prompts — accessible via HTTP, CLI, and MCP-native clients.

Quick Start

1. Build

cargo install --path .

# Optional: local ONNX vector embeddings (FastEmbed)
cargo install --path . --features semantic-search

2. Configure — create 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"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

3. Validate, then start

warmplane validate-config --config mcp_servers.json
warmplane daemon --config mcp_servers.json

Run Modes

All three modes share the same backend state, aliases, policy checks, and timeout behaviour.

HTTP Daemon

warmplane daemon --config mcp_servers.json
# Serves /v1/... on the configured port (default 9090)

Key endpoints:

MCP Server (stdio)

warmplane mcp-server --config mcp_servers.json

Point any MCP-native client at this process. It exposes lightweight facade tools (capabilities_list, capability_call, resource_read, prompt_get, …) alongside native resources/* and prompts/* methods.

Claude Desktop / Cursor config:

{
  "mcpServers": {
    "warmplane": {
      "command": "warmplane",
      "args": ["mcp-server", "--config", "mcp_servers.json"]
    }
  }
}

CLI

warmplane list-capabilities
warmplane search-capabilities "triage logs" --limit 5
warmplane describe-capability db.query

warmplane call-capability db.query \
  --params '{"query":"SELECT 1"}' \
  --request-id req-101 --actor-id user-7 \
  --idempotency-key op-20-run-1

warmplane read-resource fs.readme
warmplane get-prompt prompt.code-review --arguments '{"code":"fn main() {}"}'

warmplane list-catalog-events --after evt_3
warmplane cancel-operation req-101

Feature Overview

Changelog

v0.7.0 — Pragmatic Rust Modernization & Builder Patterns

Full adoption of Microsoft's Pragmatic Rust Guidelines (AGENTS.md). Implemented Builder Pattern (M-INIT-BUILDER) for core state (AppStateBuilder), search filters (SearchFilterBuilder), and request context (RequestContextBuilder). Enhanced error safety (M-PANIC-IS-STOP), structured logging (M-LOG-STRUCTURED), canonical documentation (M-CANONICAL-DOCS), and flexible trait interop (M-IMPL-ASREF).

v0.6.0 — Idempotency, Cancellation & Retry Metadata

Pass Idempotency-Key / X-Idempotency-Key to deduplicate concurrent tool calls. Abort any in-flight request via cancel endpoint or CLI. Every response envelope now includes structured "retry" metadata (classification + state) for orchestrator-aware retry logic.

v0.5.0 — Request Context & Correlation

Structured RequestContext (operation_id, work_item_id, actor_id, grant_id) threaded through all execution envelopes and tracing spans. HTTP header fallback (X-Request-ID, X-Operation-ID, X-Actor-ID, X-Grant-ID).

v0.4.0 — Catalog Versioning & Cache Validation

SHA-256 catalog version. ETag headers on all catalog reads, If-None-Match conditional requests returning 304 Not Modified. GET /v1/catalog/events change feed with cursor-based pagination.

v0.3.0 — Hybrid Search

POST /v1/capabilities/search with BM25 scoring, optional FastEmbed vector embeddings, tag/server-ID filters, and ranked results.

Docs