@raptorr/vendure-pi

Pi agent extension for Vendure e-commerce management. Connect to your Vendure instance and manage products, orders, customers, and more through natural language.

Requires vendure-mcp-graphql.

Installation

npm install -g vendure-mcp-graphql pi

# Then install this extension in your project:
cd /path/to/your/vendure-project
pi install /path/to/vendure-pi -l

Environment

export VENDURE_API_KEY="your-api-key"
export ADMIN_API_URL="http://localhost:3000/admin-api"   # optional
export SHOP_API_URL="http://localhost:3000/shop-api"     # optional

Usage

pi --provider quotio --model gemini-3.1-flash-lite

Then type commands like:

list 5 channel listings
show order summaries
how many products do we have?
list admin users
create a new product called "Test Product"

Built-in Tools

Tool	Description
vendure_admin_query	Execute any GraphQL query on Admin API
vendure_admin_mutation	Execute any GraphQL mutation on Admin API
vendure_shop_query	Execute any GraphQL query on Shop API
vendure_shop_mutation	Execute any GraphQL mutation on Shop API
vendure_list_admin_operations	Discover all Admin API queries and mutations
vendure_get_admin_schema	Full Admin API introspection
vendure_list_shop_operations	Discover all Shop API queries and mutations
vendure_get_shop_schema	Full Shop API introspection

Custom Tools

Define your own tools by mapping GraphQL queries/mutations to named commands. Tools are loaded from three locations (globals override earlier ones):

1. tools/default-tools.json — shipped with the package (updates with new versions)
2. ~/.pi/vendure-custom-tools.json — global user tools (shared across projects)
3. .pi/vendure-custom-tools.json — project tools (shared with your team via git)

Format

{
  "tools": [
    {
      "name": "last_orders",
      "label": "Last Orders",
      "description": "List the 5 most recent orders",
      "adminQuery": "query { orders(options: { take: 5 sort: { createdAt: DESC } }) { items { id code state total currencyCode customer { firstName lastName } } } }"
    },
    {
      "name": "mark_shipped",
      "label": "Mark Order Shipped",
      "description": "Transition an order to Shipped state",
      "adminMutation": "mutation($id: ID!) { transitionOrderToState(id: $id, state: \"Shipped\") { id state } }"
    }
  ]
}

Each tool has:

Field	Description
name	Unique tool name (prefix vendure_ is added automatically)
label	Display name shown to the agent
description	What the tool does
adminQuery	GraphQL query for Admin API read operations
shopQuery	GraphQL query for Shop API read operations
adminMutation	GraphQL mutation for Admin API write operations
shopMutation	GraphQL mutation for Shop API write operations

Use exactly one of the four API fields per tool.

Example: Project Tools

Create .pi/vendure-custom-tools.json in your Vendure project:

{
  "tools": [
    {
      "name": "daily_revenue",
      "label": "Daily Revenue",
      "description": "Total revenue from orders placed today",
      "adminQuery": "query { orders(options: { filter: { orderPlacedAt: { after: \"2026-01-01T00:00:00Z\" } } }) { items { total totalWithTax currencyCode } } }"
    }
  ]
}

New tools appear automatically on next pi run — no restart needed.

License

MIT