README

AgentZoo

Personal agent hub with MCP and a cozy UI. One server (HTTP API + MCP), one webapp, shared types.

Prerequisites

Node.js 20+
pnpm

Setup

pnpm install

Scripts

Command	Description
`pnpm dev`	Build shared types, then run server (port 3912) and webapp (port 5173) in parallel
`pnpm dev:server`	Run API + MCP server only
`pnpm dev:webapp`	Run Vite dev server only (proxies `/api` to 3912)
`pnpm build`	Build all packages
`pnpm start`	Run server (after build)

Project structure

packages/types — Shared TypeScript types (Agent, StoreShape)
packages/server — Fastify HTTP API + MCP server (stdio), JSON file store
packages/webapp — Vite + React + Tailwind, design tokens, Framer Motion

Docs

TECH-STACK.md — Stack and tooling
FRONTEND-LAYOUT.md — UI structure and flow
AESTHETICS.md — Design tokens
MCP-ARCHITECTURE.md — Store, server, and MCP flow

Cursor MCP

To use AgentZoo as an MCP server in Cursor, add to .cursor/mcp.json or Cursor settings:

{
  "mcpServers": {
    "agent-zoo": {
      "command": "pnpm",
      "args": ["--filter", "@agent-zoo/server", "run", "dev"],
      "env": {
        "AGENT_ZOO_STORE_PATH": "%USERPROFILE%/.agent-zoo/agents.json"
      }
    }
  }
}

On macOS/Linux use $HOME/.agent-zoo/agents.json for AGENT_ZOO_STORE_PATH.

Inject an agent via slash prompt

Once the MCP server is running, open a new chat in Cursor and type / to see MCP prompts. Select one of the AgentZoo prompts:

Use Current Agent — injects the currently selected agent
Use Agent: {name} — injects a specific agent

These prompts insert a user message that tells the assistant to adopt the agent's persona and active skills for the conversation.

agent-zoo