warmplane 0.7.1

# Warmplane

> **The local control plane that keeps MCP sessions warm.**  
> v0.7.0 — [Changelog](#changelog) · [User Guide](docs/USER-GUIDE.md) · [OpenAPI](docs/openapi.yaml) · [Spec](docs/spec.md)

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

```bash
cargo install --path .

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

**2. Configure** — 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"]
  },
  "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 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 |
| `GET` | `/v1/capabilities/:id` | On-demand capability detail |
| `POST` | `/v1/tools/call` | Normalized execution envelope |
| `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_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"]
    }
  }
}
```

### CLI

```bash
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

| Feature | Since | Summary |
|---------|-------|---------|
| **Alias registry** | v0.1 | Short stable aliases over upstream capability IDs |
| **Compact indexes** | v0.1 | Lazy, token-efficient catalog — detail only on demand |
| **Policy profiles** | v0.1 | Allow/deny lists, redact keys, role-scoped exposure |
| **Normalized envelopes** | v0.1 | Consistent result, timeout, and error format across all modes |
| **Hybrid search** | v0.3 | BM25 lexical + optional ONNX vector search with filters |
| **Catalog versioning** | v0.4 | SHA-256 `ETag`, `If-None-Match` → `304`, change event feed |
| **Request context** | v0.5 | `operation_id`, `actor_id`, `grant_id` in envelopes + HTTP header fallback |
| **Idempotency** | v0.6 | `Idempotency-Key` deduplication — concurrent duplicates share one result |
| **Cancellation** | v0.6 | `POST /v1/operations/:id/cancel` / `cancel-operation` CLI |
| **Retry metadata** | v0.6 | `"retry": { "classification": "safe\|unsafe\|idempotent", "state": "…" }` |
| **OTLP traces** | v0.1 | OpenTelemetry export, `trace_id` reflected in envelopes |

---

## 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

| Document | Description |
|----------|-------------|
| [docs/USER-GUIDE.md](docs/USER-GUIDE.md) | Complete usage guide: config, modes, all CLI commands, auth, policy |
| [docs/spec.md](docs/spec.md) | HTTP request/response contracts |
| [docs/openapi.yaml](docs/openapi.yaml) | OpenAPI 3.1 spec |
| [docs/config.schema.json](docs/config.schema.json) | JSON Schema for `mcp_servers.json` |
| [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) | Structured logs, OTLP config, trace correlation |
| [docs/INSTALL.md](docs/INSTALL.md) | Build variants, distribution notes |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment runbook |