warmplane

# Warmplane
[![Latest Release](https://img.shields.io/github/v/release/Warmplane/warmplane)](https://github.com/Warmplane/warmplane/releases/latest) [![crates.io](https://img.shields.io/crates/v/warmplane.svg)](https://crates.io/crates/warmplane) [![docs.rs](https://docs.rs/warmplane/badge.svg)](https://docs.rs/warmplane) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Warmplane/warmplane)
[![Rust Guideline Checks](https://github.com/Warmplane/warmplane/actions/workflows/ci.yml/badge.svg?branch=main&job=compliance-check)](https://github.com/Warmplane/warmplane/actions/workflows/ci.yml) [![Security Audit](https://github.com/Warmplane/warmplane/actions/workflows/ci.yml/badge.svg?branch=main&job=security-audit)](https://github.com/Warmplane/warmplane/actions/workflows/ci.yml)

**Security controls:** [![WORM + HMAC audit](https://img.shields.io/badge/WORM%20%2B%20HMAC-audit-4c1.svg)](docs/OBSERVABILITY.md) [![HITL + policy](https://img.shields.io/badge/HITL%20%2B%20policy-controls-4c1.svg)](docs/ENTERPRISE_FEATURES.md) [![OAuth2 + PKCE](https://img.shields.io/badge/OAuth2%20%2B%20PKCE-protected-4c1.svg)](docs/research/MCP_AUTHORIZATION.md) [![Secret redaction](https://img.shields.io/badge/secret-redaction-4c1.svg)](docs/ENTERPRISE_FEATURES.md) [![SIEM + OTLP](https://img.shields.io/badge/SIEM%20%2B%20OTLP-observable-4c1.svg)](docs/OBSERVABILITY.md)

> **The Local control plane that keeps MCP sessions warm with compact capability/resource/prompt facades.**
> 
> v0.25.2 — [Changelog](#changelog) · [User Guide](docs/USER-GUIDE.md) · [Performance](docs/PERFORMANCE.md) · [Whitepaper](docs/WHITEPAPER.md) · [OpenAPI](docs/openapi.yaml)


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. Install**

Using Homebrew (macOS & Linux):

```bash
brew tap warmplane/tap
brew install warmplane
```

Or via Cargo:

```bash
cargo install warmplane

# Optional: with local ONNX vector embeddings (FastEmbed)
cargo install warmplane --features semantic-search
```

Or from source:

```bash
git clone https://github.com/Warmplane/warmplane.git
cd warmplane
cargo install --path . --features semantic-search
```

**2. Configure Upstream Servers**

Manage servers interactively or import from existing tools:

```bash
# Interactive setup wizard
warmplane server add

# Or add non-interactively
warmplane server add filesystem --command npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
warmplane server add context7 --url "https://mcp.context7.ai/sse" --bearer-env "CONTEXT7_API_KEY"

# Or import directly from Claude Desktop / Cursor
warmplane config import
```

Or manually create `mcp_servers.json`:

```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"]
  },
  "profiles": {
    "coding": {
      "servers": ["filesystem", "sqlite"],
      "description": "Local coding and data inspection tools"
    }
  },
  "mcpServers": {
    "sqlite":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite", "./test.db"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}
```

**3. Validate, then start**

```bash
warmplane server list
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

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

Key endpoints:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/capabilities` | Compact capability index |
| `POST` | `/v1/capabilities/search` | Hybrid lexical + semantic search |
| `POST` | `/v1/tools/call` | Normalized execution envelope (supports idempotency keys, `_jsonpath`, `_limit_lines`, `_truncate_bytes`) |
| `POST` | `/v1/tools/batch_call` | Chained multi-step execution with `$step.field` reference interpolation |
| `GET` | `/v1/idempotency/records` | List cached idempotency execution records and replay counts |
| `GET` | `/v1/idempotency/records/:key` | Inspect single cached idempotency record |
| `GET` | `/v1/resources` | Resource index |
| `POST` | `/v1/resources/read` | Read resource |
| `GET` | `/v1/prompts` | Prompt index |
| `POST` | `/v1/prompts/get` | Render prompt |
| `GET` | `/v1/catalog/events` | Catalog change event feed |
| `POST` | `/v1/operations/:id/cancel` | Cancel an in-flight operation |

### MCP Server (stdio)

```bash
warmplane mcp-server --config mcp_servers.json
```

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

Claude Desktop / Cursor config:

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

### MCP Server (HTTP/SSE)

Exposes the same facade over Streamable HTTP/SSE so remote clients — CI pipelines, multi-host agent clusters, or remote desktop clients — can connect without a local process:

```bash
# Local-only (default, no auth required)
warmplane mcp-http-server --config mcp_servers.json

# Network-accessible (requires authToken in config)
warmplane mcp-http-server --config mcp_servers.json --bind 0.0.0.0 --port 9191

# Profile-restricted
warmplane mcp-http-server --config mcp_servers.json --profile coding
```

Connect from any MCP HTTP client:

```json
{
  "mcpServers": {
    "warmplane": {
      "url": "http://localhost:9191/mcp"
    }
  }
}
```

Alternatively, add an `mcpHttpServer` block to `mcp_servers.json` and the **daemon will co-host both servers** in one process:

```json
{
  "mcpHttpServer": { "port": 9191 },
  "mcpServers": { ... }
}
```

See [§4.7 of the User Guide](docs/USER-GUIDE.md#47-mcp-httparse-server-configuration-mcphttpserver) for the full config reference.

### CLI Configuration & Operations

```bash
# Interactive server setup wizard
warmplane server add

# Import settings from Claude Desktop or Cursor
warmplane config import

# Hot-reload in-memory workers from mcp_servers.json without restarting
warmplane reload

# Inspect & test servers
warmplane server list
warmplane server test github

# Ecosystem config import (Claude Desktop, Cursor, Zed)
warmplane config import

# Aliases and Policies
warmplane config alias set tool git-commit github.create_commit
warmplane config policy allow "github.*" "fetch.*"

# Capability and Execution CLI (supports --profile <name>)
warmplane list-capabilities --profile coding
warmplane search-capabilities "triage logs" --limit 5 --profile coding
warmplane describe-capability db.query --profile coding

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

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

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

---

## Performance Highlights

Warmplane is engineered with pure Rust zero-cost abstractions, keeping agent loops snappy:

- **50.4 ns** ETag Cache Validation (`If-None-Match` $\rightarrow$ `304 Not Modified`)
- **159.8 ns** Idempotent Cache-Hit Deduplication
- **1.58 µs** SHA-256 Incremental Catalog Version Hashing ($N=10$)
- **15.9 µs** Filtered Hybrid Capability Search ($N=50$)
- **372.1 µs** In-Memory Zero-Allocation Lexical Tag Search across 1,000 Tools

👉 See the complete benchmarks and profiling methodology in [docs/PERFORMANCE.md](docs/PERFORMANCE.md).

---

## Feature Overview

| Feature | Since | Summary |
|---------|-------|---------|
| **SEP-2663 Tasks Extension & Unified HITL** | v0.24.0 | Official `io.modelcontextprotocol/tasks` support with atomic state machine, asynchronous long-running tool execution (`202 Accepted` + `resultType: "task"`), cooperative cancellation (`POST /v1/tasks/:id/cancel`), TTL expiry management, and unified Human-in-the-Loop (HITL) suspension & argument resolution |
| **Exactly-Once Idempotency & Replay Ledger** | v0.23.0 | Deterministic auto-key derivation (`idk_<sha256>`), `X-Warmplane-Deduplicated: true` header caching, replay count tracking, WORM audit trail linking (`idempotency_key`, `is_replay`), and `/v1/idempotency/records` inspection APIs |
| **Embedded Rust Library Engine** | v0.23.0 | Direct in-process library interface (`EmbeddedWarmplane`, `ControlPlaneHandle`) with strongly typed response envelopes (`Envelope<T>`), direct tool/resource/prompt execution, and graceful cancellation on caller's Tokio runtime |
| **MCP HTTP/SSE Server Mode** | v0.22.0 | Streamable HTTP/SSE MCP server (`mcp-http-server`) for remote network clients; daemon co-hosting via `mcpHttpServer` config block; profile restriction, auth enforcement on non-loopback bind, graceful shared-state shutdown |
| **Signal Handling & Graceful Teardown** | v0.21.0 | Immediate signal cancellation (`CancellationToken`), instant SSE stream termination, clean stdio child orphan protection (`kill_on_drop`), and bounded drain safety timeouts |
**3. Run & Connect**

```bash
# Start HTTP daemon & Web Control Deck on http://127.0.0.1:9090
warmplane daemon

# Expos