Toggle documentation navigation
Automata
Source
Contribute

Development

Automata is a pnpm workspace with a Nuxt web app and a Telegram bridge. This page orients you before changing the source.

Repository layout

apps/
  web/              Nuxt app: management UI and MCP endpoint
  telegram-bridge/  Personal-account Telegram bridge
docs/               Source documentation
docker-compose.dev.yml   Supporting services for local development

Start the supporting services from the local deployment guide, then run pnpm dev on the host so hot module replacement works.

Scripts

CommandPurpose
pnpm devRun the Nuxt app on the host
pnpm services:up, :whatsapp, :telegramStart service profiles
pnpm services:down, services:logs, services:psStop, inspect, and tail services
pnpm typecheckType-check the web app

There is no predev hook, so start the services your connector needs before pnpm dev.

Authentication paths

The two surfaces never share credentials:

  • Management routes require the HTTP-only session cookie, stored as a SHA-256 hash in the app schema.
  • The MCP endpoint accepts only a connector token, from Authorization: Bearer or the /mcp/<token> path, and never falls back to a session.

Invalid tokens receive 401 with WWW-Authenticate. A database outage returns 503, so a transient failure is never mistaken for a revoked token. See How Automata works.

Add an MCP tool

Tools live under apps/web/server/mcp/tools, grouped by connection kind.

  1. Define the tool in the folder for its kind, with a read, write, or destructive annotation.
  2. Register it for that kind only. Other kinds must never see it.
  3. Resolve the connection from the token, never from a tool argument.
  4. Enforce action scope and any chat or table allowlist on the server, before touching upstream data.
  5. Document it in the MCP tools reference.
View source