Skip to main content

Chapter 9: The aip.json Schema

TL;DR​

The aip.json file is the manifest that describes your pack to the Worka Host. Here is an example with key fields explained.

{
  // --- Required Identity --- 
  "tenant": "my-github-username",
  "name": "my-cool-pack",
  "version": "0.1.0",

  // --- Presentation in UI ---
  "display_name": "My Cool Pack",
  "description": "This pack does amazing things.",

  // --- Backend Server Definitions ---
  "mcp_servers": {
    "main_svc": { // A unique name for the server
      "image": "my-cool-pack-main-svc:latest", // The Docker image to run
      "command": ["/usr/local/bin/my_server_binary"], // Command to execute
      // "input_schema": [...] // Optional: Defines a config form for the user
    }
  },
  "main_mcp_server": "main_svc", // Which server is the primary one

  // --- Security & Dependencies ---
  "capabilities": ["net.access"], // Permissions the pack needs
  "dependencies": ["worka/browser"] // Other packs this pack uses
}

Every pack requires an aip.json file in its root directory. This manifest acts as a contract between your pack and the Worka Host, providing all the metadata needed to build, run, and display your pack correctly.

Let's break down the key sections of the file.

Root Properties: Identity and Presentation​

These fields define the core identity of your pack and how it appears in the Worka UI.

  • tenant (string, required): A unique namespace, like a publisher ID. Your GitHub username is a good choice.
  • name (string, required): The machine-readable name of the pack (e.g., my-cool-pack).
  • version (string, required): The version of your pack, following Semantic Versioning (e.g., 0.1.0).
  • display_name (string, required): The human-readable name shown in the UI (e.g., "My Cool Pack").
  • description (string, required): A brief description of what your pack does.
  • author (string, optional): The name and/or email of the pack author.

Backend Logic: mcp_servers​

This object defines the backend servers your pack needs to run.

  • mcp_servers (object, optional): An object where each key is a unique name for one of your backend servers.
    • image (string): The name of the Docker image to run for this server.
    • command (array of strings): The command to execute inside the container to start the server.
    • args (array of strings, optional): Arguments to pass to the command.
    • env (object, optional): A map of environment variables to set inside the container.
    • input_schema (array, optional): A schema defining configuration options (like API keys) that your pack needs. Worka will use this to automatically generate a settings form for the user upon installation.
  • main_mcp_server (string, optional): If you have multiple servers, this specifies which one is the primary backend for the pack.

User Interface: views​

This section defines the UI components that your pack provides. You do not need to edit this section manually. The worka bundle command will analyze your views/ directory and automatically generate this part of the manifest for you.

Security and Dependencies​

These fields define your pack's relationship with the host and other packs.

  • capabilities (array of strings, optional): A critical security feature. This is a list of permissions your pack requires to function, such as "net.access" to access the internet or "ui.tabs.open" to open a new tab in the Worka UI. Your pack will be denied from performing these actions if they are not declared here.
  • dependencies (array of strings, optional): A list of other packs that your pack depends on, identified by their <tenant>/<name>. Declaring a dependency is required to be able to call tools from that pack.