Skip to main content

Chapter 2: The Anatomy of an AI Pack

TL;DR​

A pack is a directory with a conventional structure. The key components are:

my-cool-pack/
├── aip.json         # The manifest. Declares identity, capabilities, UI views, and MCP servers.
├── views/           # Contains React components (.tsx). Each file is a dynamically loaded view.
├── mcp/             # Contains backend logic. Each subdirectory is a separate MCP server.
│   └── my_server/   # Can be Rust (Cargo.toml) or Node.js (package.json).
├── assets/          # (Optional) Static images, icons, etc.
├── locales/         # (Optional) i18n translation files.
└── sql/             # (Optional) Database migration files for a pack-specific schema.

At its core, an AI Pack is just a folder with a specific, conventional structure. The Worka Host Application reads this folder to understand what the pack does, how to run it, and how to display it to the user.

A pack is built on three fundamental pillars.

Pillar 1: The User Interface (views/)​

This is what the user sees. The views/ directory in your pack contains all of the UI components. These are standard React components written in .tsx files. Each file in this directory can be treated as a separate "page" or view that can be opened in a tab within the Worka application. You build these just like you would any other React component, using familiar tools and libraries like Chakra UI for styling.

Pillar 2: The Backend Logic (mcp/)​

This is where your pack's unique capabilities live. The mcp/ directory contains the source code for one or more backend servers. These servers follow a specific standard called the Model Context Protocol (MCP), which is why we call them MCP Servers.

An MCP Server's job is to expose Tools that can be called by your UI or by an AI Agent. A "Tool" is simply a function that performs an action—for example, get_weather, send_tweet, or summarize_text.

Worka's CLI has first-class support for building MCP servers written in Rust and Node.js, but you can write one in any language (like Python or Go) and package it in a Docker container, which the Worka Host can run.

Pillar 3: The Manifest (aip.json)​

The aip.json file is the most important file in your pack. It is the "ID card" or "contract" that describes your pack to the Worka Host. It's a simple JSON file that tells the Host everything it needs to know:

  • Identity: What is the pack's unique name and who is the author (tenant)?
  • Presentation: What is its user-friendly display name and description?
  • Contents: What UI views does it have? What MCP servers does it need to run?
  • Permissions: What special capabilities does it need (e.g., access to the internet)?

The Host reads this file to know how to build, run, and display your pack, and to enforce its security sandbox.