Add MCP client plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

MCP_CLIENT_PLAN.md

@@ -0,0 +1,27 @@
+# MCP Client Plan
+
+## Goal
+Add an MCP client mode to Yaak so users can connect to and debug MCP servers.
+
+## Core Design
+- **Protocol layer:** Implement JSON‑RPC framing, message IDs, and notifications as the common core.
+- **Transport interface:** Define an async trait with `connect`, `send`, `receive`, and `close` methods.
+- **Transports:**
+  - Start with **Standard I/O** for local development.
+  - Reuse the existing HTTP stack for **HTTP streaming** next.
+  - Leave hooks for **WebSocket** support later.
+
+## Integration
+- Register MCP as a new request type alongside REST, GraphQL, gRPC, and WebSocket.
+- Allow per‑request transport selection (stdio or HTTP).
+- Map inbound messages into a new MCP response model that feeds existing timeline and debug views.
+
+## Testing and Dog‑fooding
+- Convert Yaak's own MCP server to Standard I/O for local testing.
+- Use it internally to validate protocol behavior and message flow.
+- Add unit and integration tests for JSON‑RPC messaging and transport abstractions.
+
+## Future Refinements
+- Add WebSocket transport support once core paths are stable.
+- Extend timelines for protocol‑level visualization layered over raw transport events.
+- Implement version and capability negotiation between client and server.

crates-cli/yaak-cli/PLAN.md

@@ -0,0 +1,198 @@
+# CLI Command Architecture Plan
+
+## Goal
+
+Redesign the yaak-cli command structure to use a resource-oriented `<resource> <action>`
+pattern that scales well, is discoverable, and supports both human and LLM workflows.
+
+## Command Architecture
+
+### Design Principles
+
+- **Resource-oriented**: top-level commands are nouns, subcommands are verbs
+- **Polymorphic requests**: `request` covers HTTP, gRPC, and WebSocket — the CLI
+  resolves the type via `get_any_request` and adapts behavior accordingly
+- **Simple creation, full-fidelity via JSON**: human-friendly flags for basic creation,
+  `--json` for full control (targeted at LLM and scripting workflows)
+- **Runtime schema introspection**: `request schema` outputs JSON Schema for the request
+  models, with dynamic auth fields populated from loaded plugins at runtime
+- **Destructive actions require confirmation**: `delete` commands prompt for user
+  confirmation before proceeding. Can be bypassed with `--yes` / `-y` for scripting
+
+### Commands
+
+```
+# Top-level shortcut
+yaakcli send <id> [-e <env_id>]          # id can be a request, folder, or workspace
+
+# Resource commands
+yaakcli workspace list
+yaakcli workspace show <id>
+yaakcli workspace create --name <name>
+yaakcli workspace create --json '{"name": "My Workspace"}'
+yaakcli workspace create '{"name": "My Workspace"}'              # positional JSON shorthand
+yaakcli workspace update --json '{"id": "wk_abc", "name": "New Name"}'
+yaakcli workspace delete <id>
+
+yaakcli request list <workspace_id>
+yaakcli request show <id>
+yaakcli request create <workspace_id> --name <name> --url <url> [--method GET]
+yaakcli request create --json '{"workspaceId": "wk_abc", "url": "..."}'
+yaakcli request update --json '{"id": "rq_abc", "url": "https://new.com"}'
+yaakcli request send <id> [-e <env_id>]
+yaakcli request delete <id>
+yaakcli request schema <http|grpc|websocket>
+
+yaakcli folder list <workspace_id>
+yaakcli folder show <id>
+yaakcli folder create <workspace_id> --name <name>
+yaakcli folder create --json '{"workspaceId": "wk_abc", "name": "Auth"}'
+yaakcli folder update --json '{"id": "fl_abc", "name": "New Name"}'
+yaakcli folder delete <id>
+
+yaakcli environment list <workspace_id>
+yaakcli environment show <id>
+yaakcli environment create <workspace_id> --name <name>
+yaakcli environment create --json '{"workspaceId": "wk_abc", "name": "Production"}'
+yaakcli environment update --json '{"id": "ev_abc", ...}'
+yaakcli environment delete <id>
+
+```
+
+### `send` — Top-Level Shortcut
+
+`yaakcli send <id>` is a convenience alias that accepts any sendable ID. It tries
+each type in order via DB lookups (short-circuiting on first match):
+
+1. Request (HTTP, gRPC, or WebSocket via `get_any_request`)
+2. Folder (sends all requests in the folder)
+3. Workspace (sends all requests in the workspace)
+
+ID prefixes exist (e.g. `rq_`, `fl_`, `wk_`) but are not relied upon — resolution
+is purely by DB lookup.
+
+`request send <id>` is the same but restricted to request IDs only.
+
+### Request Send — Polymorphic Behavior
+
+`send` means "execute this request" regardless of protocol:
+
+- **HTTP**: send request, print response, exit
+- **gRPC**: invoke the method; for streaming, stream output to stdout until done/Ctrl+C
+- **WebSocket**: connect, stream messages to stdout until closed/Ctrl+C
+
+### `request schema` — Runtime JSON Schema
+
+Outputs a JSON Schema describing the full request shape, including dynamic fields:
+
+1. Generate base schema from `schemars::JsonSchema` derive on the Rust model structs
+2. Load plugins, collect auth strategy definitions and their form inputs
+3. Merge plugin-defined auth fields into the `authentication` property as a `oneOf`
+4. Output the combined schema as JSON
+
+This lets an LLM call `schema`, read the shape, and construct valid JSON for
+`create --json` or `update --json`.
+
+## Implementation Steps
+
+### Phase 1: Restructure commands (no new functionality)
+
+Refactor `main.rs` into the new resource/action pattern using clap subcommand nesting.
+Existing behavior stays the same, just reorganized. Remove the `get` command.
+
+1. Create module structure: `commands/workspace.rs`, `commands/request.rs`, etc.
+2. Define nested clap enums:
+   ```rust
+   enum Commands {
+       Send(SendArgs),
+       Workspace(WorkspaceArgs),
+       Request(RequestArgs),
+       Folder(FolderArgs),
+       Environment(EnvironmentArgs),
+   }
+   ```
+3. Move existing `Workspaces` logic into `workspace list`
+4. Move existing `Requests` logic into `request list`
+5. Move existing `Send` logic into `request send`
+6. Move existing `Create` logic into `request create`
+7. Delete the `Get` command entirely
+8. Extract shared setup (DB init, plugin init, encryption) into a reusable context struct
+
+### Phase 2: Add missing CRUD commands
+
+1. `workspace show <id>`
+2. `workspace create --name <name>` (and `--json`)
+3. `workspace update --json`
+4. `workspace delete <id>`
+5. `request show <id>` (JSON output of the full request model)
+6. `request delete <id>`
+7. `folder list <workspace_id>`
+8. `folder show <id>`
+9. `folder create <workspace_id> --name <name>` (and `--json`)
+10. `folder update --json`
+11. `folder delete <id>`
+12. `environment list <workspace_id>`
+13. `environment show <id>`
+14. `environment create <workspace_id> --name <name>` (and `--json`)
+15. `environment update --json`
+16. `environment delete <id>`
+
+### Phase 3: JSON input for create/update
+
+Both commands accept JSON via `--json <string>` or as a positional argument (detected
+by leading `{`). They follow the same upsert pattern as the plugin API.
+
+- **`create --json`**: JSON must include `workspaceId`. Must NOT include `id` (or
+  use empty string `""`). Deserializes into the model with defaults for missing fields,
+  then upserts (insert).
+- **`update --json`**: JSON must include `id`. Performs a fetch-merge-upsert:
+  1. Fetch the existing model from DB
+  2. Serialize it to `serde_json::Value`
+  3. Deep-merge the user's partial JSON on top (JSON Merge Patch / RFC 7386 semantics)
+  4. Deserialize back into the typed model
+  5. Upsert (update)
+
+  This matches how the MCP server plugin already does it (fetch existing, spread, override),
+  but the CLI handles the merge server-side so callers don't have to.
+
+  Setting a field to `null` removes it (for `Option<T>` fields), per RFC 7386.
+
+Implementation:
+1. Add `--json` flag and positional JSON detection to `create` commands
+2. Add `update` commands with required `--json` flag
+3. Implement JSON merge utility (or use `json-patch` crate)
+
+### Phase 4: Runtime schema generation
+
+1. Add `schemars` dependency to `yaak-models`
+2. Derive `JsonSchema` on `HttpRequest`, `GrpcRequest`, `WebsocketRequest`, and their
+   nested types (`HttpRequestHeader`, `HttpUrlParameter`, etc.)
+3. Implement `request schema` command:
+   - Generate base schema from schemars
+   - Query plugins for auth strategy form inputs
+   - Convert plugin form inputs into JSON Schema properties
+   - Merge into the `authentication` field
+   - Print to stdout
+
+### Phase 5: Polymorphic send
+
+1. Update `request send` to use `get_any_request` to resolve the request type
+2. Match on `AnyRequest` variant and dispatch to the appropriate sender:
+   - `AnyRequest::HttpRequest` — existing HTTP send logic
+   - `AnyRequest::GrpcRequest` — gRPC invoke (future implementation)
+   - `AnyRequest::WebsocketRequest` — WebSocket connect (future implementation)
+3. gRPC and WebSocket send can initially return "not yet implemented" errors
+
+### Phase 6: Top-level `send` and folder/workspace send
+
+1. Add top-level `yaakcli send <id>` command
+2. Resolve ID by trying DB lookups in order: any_request → folder → workspace
+3. For folder: list all requests in folder, send each
+4. For workspace: list all requests in workspace, send each
+5. Add execution options: `--sequential` (default), `--parallel`, `--fail-fast`
+
+## Crate Changes
+
+- **yaak-cli**: restructure into modules, new clap hierarchy
+- **yaak-models**: add `schemars` dependency, derive `JsonSchema` on model structs
+  (current derives: `Debug, Clone, PartialEq, Serialize, Deserialize, Default, TS`)