piu-mcp

# PIU MCP Toolkit PIU exposes 57 MCP tools via Streamable HTTP at `http://127.0.0.1:3333/mcp`. The CLI handles session management automatically. ## Prerequisites - PIU desktop app running with MCP server enabled (Settings > MCP > Start Server) - Bun runtime installed ## CLI This skill bundles `scripts/piu.ts` (relative to this SKILL.md). Run it with Bun: ```bash bun scripts/piu.ts <command> [args...] ``` All commands that take structured input accept a JSON string argument. All output is JSON. ## Projects (6 tools) ```bash bun scripts/piu.ts list-projects bun scripts/piu.ts get-project <project_id> bun scripts/piu.ts create-project '{"name":"my-api","description":"My API","source_repo_url":"https://github.com/org/repo","backend_type":"express"}' bun scripts/piu.ts update-project '{"project_id":"...","name":"New Name","source_commit_id":"abc123"}' bun scripts/piu.ts delete-project <project_id> ``` The `overview` and `tree` workflow commands provide formatted summaries: ```bash bun scripts/piu.ts overview <project_id> # Compact summary bun scripts/piu.ts tree <project_id> # Full tree with envs, collections, methods ``` ## Collections (5 tools) ```bash bun scripts/piu.ts list-collections <project_id> bun scripts/piu.ts get-collection <collection_id> bun scripts/piu.ts create-collection '{"project_id":"...","name":"Users","path_prefix":"/users","description":"User management"}' bun scripts/piu.ts update-collection '{"collection_id":"...","name":"Auth","path_prefix":"/auth"}' bun scripts/piu.ts delete-collection <collection_id> ``` Collections support nesting via `parent_id` and shared headers via `shared_headers` (JSON string). ## Requests (6 tools + search) ```bash bun scripts/piu.ts list-requests <collection_id> bun scripts/piu.ts get-request <request_id> bun scripts/piu.ts create-request '{"collection_id":"...","name":"Login","config":{"method":"POST","url":"/login","headers":[],"params":[],"body":{"type":"json","content":"{\"username\":\"admin\"}"},"auth":{"type":"none"},"description":"Authenticate user"}}' bun scripts/piu.ts update-request '{"request_id":"...","config":{"method":"POST","url":"/login","body":{"type":"json","content":"{}"}}}' bun scripts/piu.ts delete-request <request_id> bun scripts/piu.ts duplicate-request <request_id> bun scripts/piu.ts search <project_id> <query> [method] ``` ### Request config shape ```json { "method": "POST", "url": "/path", "headers": [{"key": "Content-Type", "value": "application/json", "enabled": true}], "params": [{"key": "page", "value": "1", "enabled": true}], "body": {"type": "json", "content": "{\"key\": \"value\"}"}, "auth": {"type": "bearer", "token": "{{token}}"}, "description": "## POST /path\n\nEndpoint description..." } ``` URL resolution: `env.host + collection.path_prefix + request.url` ## Environments (8 tools) ```bash bun scripts/piu.ts list-envs <project_id> bun scripts/piu.ts get-env <environment_id> bun scripts/piu.ts create-env '{"project_id":"...","name":"Development","host":"http://localhost:3000"}' bun scripts/piu.ts update-env '{"environment_id":"...","name":"Staging","host":"https://staging.api.com"}' bun scripts/piu.ts delete-env <environment_id> bun scripts/piu.ts activate-env '{"environment_id":"...","project_id":"..."}' bun scripts/piu.ts get-vars <environment_id> bun scripts/piu.ts set-vars '{"environment_id":"...","variables":[{"key":"token","value":"abc","enabled":true}]}' ``` `set-vars` uses upsert-by-key: existing variables with matching keys are updated (preserving their IDs and hook associations), new keys are inserted, absent keys are deleted. Returns full variable records with IDs. Activate an environment before executing requests — it sets the host URL for URL resolution. ## Hooks (5 tools) Response hooks auto-extract values from HTTP responses and write them to environment variables. Use these to set up auth token flows (e.g., login → extract token → set variable). ```bash bun scripts/piu.ts tool create_hook '{"environment_id":"...","source_request_id":"LOGIN_REQ_ID","response_location":"body","selector":"data.token","target_variable_ids":["VAR_ID_1","VAR_ID_2"],"expires_in":3600000,"array_strategy":"first"}' bun scripts/piu.ts tool list_hooks '{"environment_id":"..."}' bun scripts/piu.ts tool get_hook '{"hook_id":"..."}' bun scripts/piu.ts tool update_hook '{"hook_id":"...","selector":"data.access_token","enabled":true}' bun scripts/piu.ts tool delete_hook '{"hook_id":"..."}' ``` ### Hook fields - **source_request_id** — The request whose response triggers extraction - **response_location** — `"body"` (JSONPath on response body) or `"header"` (header name) - **selector** — JSONPath expression (e.g. `data.token`) or header name - **target_variable_ids** — Variable IDs to update with extracted value (get IDs from `set-vars` response) - **value_template** — Transform template, default `"{{value}}"` - **expires_in** — TTL in **milliseconds** (e.g. 3600000 = 1 hour). Sets variable `expires_at` - **array_strategy** — `"pick"` (UI picker), `"first"`, or `"last"`. Note: only `"pick"` is fully implemented in the UI; `"first"`/`"last"` are stored but not yet executed at runtime ### Hook workflow 1. Create variables via `set-vars` (returns variable records with stable IDs) 2. Create hook pointing source request → target variables 3. Execute source request via MCP — hooks fire automatically and update target variables 4. Subsequent requests using `{{variable}}` get the extracted values ## Variables (1 tool) Update a single variable without replacing all variables in the environment. ```bash bun scripts/piu.ts tool update_variable '{"variable_id":"...","value":"new-token","match_paths":"[\"/admin/*\"]","target_location":"auth-bearer"}' ``` Fields: `value`, `match_paths` (JSON array of globs), `target_location` (header, url-param, url-path, body, auth-bearer, auth-basic-username, auth-basic-password, auth-custom), `expires_at` (epoch ms), `priority` (integer), `enabled` (boolean). All optional — only provided fields are updated. ## Data Models (11 tools) Models define typed schemas for request/response bodies. They support single-parent inheritance and multi-mixin composition. ```bash bun scripts/piu.ts list-models <project_id> bun scripts/piu.ts get-model <model_id> bun scripts/piu.ts create-model '{"project_id":"...","name":"LoginRequest","description":"Auth payload","fields":[{"name":"username","field_type":"string","required":true,"example":"admin"},{"name":"password","field_type":"string","required":true}]}' bun scripts/piu.ts update-model '{"model_id":"...","name":"NewName","fields":[...]}' bun scripts/piu.ts delete-model <model_id> bun scripts/piu.ts generate-body <model_id> bun scripts/piu.ts validate '{"model_id":"...","response_body":"{\"code\":0,\"data\":{}}"}' bun scripts/piu.ts resolve-fields <model_id> ``` Field types: `string`, `integer`, `number`, `boolean`, `array`, `object`, `file` ### Inheritance & Mixins ```bash # Create base model, then child with parent_model_id bun scripts/piu.ts create-model '{"project_id":"...","name":"PaginatedResponse","parent_model_id":"BASE_MODEL_ID","fields":[{"name":"items","field_type":"array"}]}' # Or use mixins for composition bun scripts/piu.ts create-model '{"project_id":"...","name":"UserList","mixin_model_ids":["PAGINATION_ID","SEARCH_ID"],"fields":[...]}' ``` `resolve-fields` returns all fields including inherited and mixin fields in linearized order. ## Model Relations (6 tools) ```bash bun scripts/piu.ts model-graph <project_id> # All model relationships (JSON) bun scripts/piu.ts model-hierarchy <model_id> # Ancestry chain for one model bun scripts/piu.ts model-mermaid <project_id> # Mermaid class diagram bun scripts/piu.ts link-model '{"request_id":"...","model_type":"request","model_id":"..."}' bun scripts/piu.ts unlink-model '{"request_id":"...","model_type":"response"}' bun scripts/piu.ts request-models <request_id> # Get linked request + response models ``` `model_type` is either `"request"` or `"response"`. ## Execution (1 tool) ```bash bun scripts/piu.ts execute <request_id> ``` Resolves URL (`env.host + collection.prefix + request.url`), interpolates `{{variables}}`, injects auth, sends HTTP via reqwest, and returns status, headers, body, timing. Execute resolves variables, injects auth, sends the request, and **fires response hooks** — any hook whose source request matches will extract values and update target variables automatically. ### Batch verification ```bash bun scripts/piu.ts verify <project_id> # Execute all GET requests, report pass/fail ``` ## Search & Discovery (5 tools) Full-text search across all entity types with BM25 ranking and entity relationship traversal. ```bash # FTS5 search across all entities bun scripts/piu.ts search-entities '{"query":"users","project_id":"...","entity_type":"request","limit":20}' # Find related entities (Obsidian-style backlinks) bun scripts/piu.ts find-related <entity_type> <entity_id> [max_depth] # Detailed view of any entity bun scripts/piu.ts entity-detail <entity_type> <entity_id> # Complete API surface for a project (all methods + paths) bun scripts/piu.ts api-surface <project_id> # Natural-language project summary bun scripts/piu.ts summary <project_id> ```