ai-factory-extension-hello-template

A minimal template for packaging MCP servers as an ai-factory extension. Use it to quickly distribute one or more MCP servers across all agents managed by ai-factory.

Quick Start

1. Click "Use this template" on GitHub to create your own repository from this template, then clone it. Alternatively, fork or clone this repository directly.
2. Edit extension.json — set your extension name, version, description, and list every MCP server in the mcpServers array.
3. For each server, create a JSON template in the mcp/ directory.
4. Install the extension into your project:

# from a local directory
ai-factory extension add ./ai-factory-extension-hello-template

# or from a git repo
ai-factory extension add https://github.com/<user>/<repo>.git

That's it — ai-factory merges the MCP server configs into every agent that supports MCP (Claude Code, Cline, etc.).

Project Structure

ai-factory-extension-hello-template/
├── .github/
│   └── workflows/
│       └── test.yml             # CI workflow
├── commands/
│   └── hello.js                 # Custom CLI command
├── injections/
│   └── implement-extra.md       # Injection appended to aif-implement
├── mcp/
│   └── hello-mcp.json           # MCP server template
├── skills/
│   ├── aif-hello-world/
│   │   └── SKILL.md             # Custom skill
│   └── hello-commit/
│       └── SKILL.md             # Skill replacing aif-commit
├── extension.json               # Extension manifest (required)
├── package.json
├── LICENSE
└── README.md

How It Works

extension.json

The manifest declares which MCP servers the extension provides:

{
  "name": "ai-factory-extension-hello-template",
  "version": "1.0.0",
  "description": "Template: hello MCP server inside ai-factory extension",
  "mcpServers": [
    {
      "key": "playwright",
      "template": "./mcp/playwright.json",
      "instruction": "Playwright MCP: Install Chrome to use a web browser"
    }
  ]
}

MCP Template (mcp/*.json)

Each template follows the standard MCP server format:

{
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}

You can also pass environment variables:

{
  "command": "npx",
  "args": ["-y", "@my-org/my-mcp-server"],
  "env": {
    "MY_API_KEY": "${MY_API_KEY}"
  }
}

Adding More MCP Servers

1. Create a new template file in mcp/, e.g. mcp/my-server.json.
2. Add a new entry to the mcpServers array in extension.json:

{
  "key": "my-server",
  "template": "./mcp/my-server.json",
  "instruction": "Set MY_API_KEY environment variable before use"
}

3. Re-install the extension to apply:

ai-factory extension remove ai-factory-extension-hello-template
ai-factory extension add ./ai-factory-extension-hello-template

Managing the Extension

# List installed extensions
ai-factory extension list

# Remove the extension (cleans up MCP entries from agent configs)
ai-factory extension remove ai-factory-extension-hello-template

Documentation

• ai-factory Extensions Guide — full reference for extension manifest fields, MCP servers, injections, commands, skills, and agents.

License

MIT