# Piu MCP

> Full PIU API management toolkit — 57 MCP tools for managing projects, collections, requests, environments, data models, execution, search, sync, and OpenAPI generation. Use this skill whenever you need to interact with PIU — whether creating projects, sending API requests, managing environments, querying the knowledge graph, generating OpenAPI specs, or any task involving PIU data. Always activate when the user mentions PIU, API management, MCP tools, or any operation on API projects/collections/requests.

- Skill: `dickwu/piu-mcp` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dickwu/piu-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dickwu/piu-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dickwu (https://skillmd.com/u/dickwu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dickwu/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>
```

Entity types: `project`, `collection`, `request`, `model`, `environment`

## Sync & Changelog (2 tools)

```bash
bun scripts/piu.ts sync-status <project_id>     # Pretty-print with staleness indicators
bun scripts/piu.ts changelog '{"entity_type":"request","entity_id":"...","limit":20}'
bun scripts/piu.ts diff-sync <project_id> <repo_path>  # Compare repo HEAD vs PIU commit
```

Every entity tracks `source_commit_id`. `sync-status` flags entities whose commit differs from the project-level commit.

## OpenAPI (2 tools)

```bash
bun scripts/piu.ts generate-spec <project_id>   # Generate OpenAPI 3.1 spec from project data
bun scripts/piu.ts get-spec <project_id>         # Retrieve previously generated spec
```

## Batch Operations (5 tools)

All batch commands read JSON from stdin.

```bash
# Batch create requests
cat routes.json | bun scripts/piu.ts batch-requests
# Input: [{"collection_id":"...","name":"List Users","method":"GET","url":"/list"}]

# Batch create collections
cat cols.json | bun scripts/piu.ts batch-collections
# Input: [{"project_id":"...","name":"Users","path_prefix":"/users"}]

# Batch update request configs
cat updates.json | bun scripts/piu.ts batch-update-bodies
# Input: [{"request_id":"...","name":"Login","config":{...}}]

# Batch create models
cat models.json | bun scripts/piu.ts batch-models
# Input: {"project_id":"...","models":[{"name":"LoginRequest","fields":[...]}]}

# Batch link models to requests
cat links.json | bun scripts/piu.ts batch-links
# Input: [{"request_id":"...","model_type":"request","model_id":"..."}]
```

## Generic Tool Call

For any MCP tool not covered by a named command:

```bash
bun scripts/piu.ts tool <tool_name> '<json_args>'
bun scripts/piu.ts tool search_entities '{"query":"auth","entity_type":"request"}'
```

## All 57 MCP Tools

| Domain | Tools |
|--------|-------|
| Projects (6) | `list_projects`, `get_project`, `get_project_overview`, `create_project`, `update_project`, `delete_project` |
| Collections (5) | `list_collections`, `get_collection`, `create_collection`, `update_collection`, `delete_collection` |
| Requests (6) | `list_requests`, `get_request`, `create_request`, `update_request`, `delete_request`, `duplicate_request` |
| Environments (8) | `list_environments`, `get_environment`, `create_environment`, `update_environment`, `delete_environment`, `set_active_environment`, `list_env_variables`, `set_env_variables`, `update_variable` |
| Hooks (5) | `create_hook`, `list_hooks`, `get_hook`, `update_hook`, `delete_hook` |
| Models (8) | `list_models`, `get_model`, `create_model`, `update_model`, `delete_model`, `generate_body_from_model`, `validate_response_against_model`, `resolve_model_fields` |
| Model Batch (2) | `batch_create_models`, `batch_link_models` |
| Model Relations (3) | `get_model_relations`, `get_model_hierarchy`, `get_model_diagram` |
| Linking (3) | `link_model_to_request`, `unlink_model_from_request`, `get_request_models` |
| Execution (1) | `execute_request` |
| Search (6) | `search_requests`, `search_entities`, `find_related_entities`, `get_entity_detail`, `get_api_surface`, `get_project_summary` |
| Sync (2) | `get_sync_status`, `get_changelog` |
| OpenAPI (2) | `generate_openapi_spec`, `get_openapi_spec` |