piu-mcp

name

piu-mcp

description

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.

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:

bun scripts/piu.ts <command> [args...]

All commands that take structured input accept a JSON string argument. All output is JSON.

Projects (6 tools)

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:

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)

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)

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

{
  "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)

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).

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.

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.

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

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

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)

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

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.

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

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)

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.

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

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