MCP Moira

Agent Workflow Engine for AI agents.

Primary users: AI agents via MCP protocol. Web UI is supplementary for workflow management.

See docs/VISION.md for product vision and design principles.

Two ways to run Moira

• Self-host (this repository, Apache-2.0) — run the full engine + Web UI + MCP server in a single Docker container on your own infrastructure. Free and open source; your data stays with you. Start in the Quick Start below.
• Moira Cloud (managed) — a hosted instance with nothing to operate, at moira-mcp.com.

Both run the same engine and MCP tools. Self-host is a single-tenant private-team deployment with administrator-approved accounts. Cloud adds managed hosting and SaaS-only policy and administration, including social login, legal consent, email verification, and the broader multi-user administration surface.

Architecture

Monorepo: Clean separation of concerns with npm workspaces Workflow Engine: Node-graph execution over a set of node types (@mcp-moira/workflow-engine) MCP Server: HTTP protocol server exposing the MCP tools (@mcp-moira/mcp-server) Web Backend: Express API server (@mcp-moira/web-backend) Web Frontend: React UI with webpack (@mcp-moira/web-frontend) Docs: Astro 5 + Starlight documentation site, EN+RU (@mcp-moira/docs) Shared: Database layer + Better Auth + logging (@mcp-moira/shared) Database: Modular repository pattern with Drizzle ORM Settings System: Universal settings with encryption and dynamic UI generation Docker Deployment: Multi-stage container with TypeScript validation Validation: JSON Schema with AJV

Package Structure

• packages/workflow-engine/ - Core node-graph execution engine
• packages/extension-sdk/ - Typed authoring contract for custom nodes and communication channels
• packages/extension-runner/ - Isolated companion service for installed extension bundles
• packages/mcp-server/ - MCP protocol HTTP server with tools
• packages/web-backend/ - Express API for workflow management
• packages/web-frontend/ - React UI for workflow visualization
• packages/docs/ - Astro 5 + Starlight documentation site (EN+RU), built into the image and served at /docs
• packages/shared/ - Database layer (schema, connection, repositories) + Better Auth + logging
  • database/ - Modular repositories (Workflow, Execution, Settings)
  • auth/ - Better Auth configuration
  • logging/ - Structured logging
• Docker Config (config/) - Unified container deployment configuration

Quick Start

Self-Host (recommended)

Run a complete Moira instance locally with Docker — no source build required:

cp .env.example .env       # defaults work locally; review host, port, and artifact domain for another host
docker compose up -d

Then open:

• Web UI: http://localhost:8080
• Documentation: http://localhost:8080/docs/
• MCP endpoint: http://localhost:8080/mcp

The image is pulled from the public registry by default. Data (SQLite + execution storage) persists in ./data. See Self-Hosting or the in-app docs at /docs/ for the full reference.

Updating / Upgrading

Update a normal self-host installation with the standard Compose commands:

docker compose pull
docker compose up -d
docker compose ps

Older .env files may still override Compose with the removed 0.3.5 tag; change that line once to MOIRA_IMAGE=ghcr.io/moira-mcp/moira:latest before updating.

The image protects existing self-host data before its startup migrations: it creates and verifies a coherent SQLite backup, includes the prompt manifest, and keeps three rotating recovery states under data/.moira-startup-backups/. If initialization fails, it restores the database and manifest before refusing to start the services. A persistent pending marker also restores the verified state before the next attempt if the container or host was interrupted mid-initialization. A fresh installation skips the nonexistent-database backup and uses only a temporary persistent marker so an interrupted first start is removed before retry.

The complete automatic recovery behavior and optional pinned-image preflight are documented in Self-hosting: Updating and Recovery, with a matching Russian version. Release notes are on the GitHub Releases page.

Local Development (from source)

For contributors who want to build and run from the source tree, switch docker-compose.yml to Option B first — comment out the image: line and uncomment the build: block (the file documents both options inline). Then:

nvm use
npm install
docker compose up -d --build   # builds the image locally from config/Dockerfile
# Web UI: http://localhost:8080  |  MCP: http://localhost:8080/mcp

(The default docker-compose.yml uses the prebuilt public image — docker compose up -d without --build — which is the recommended self-host path.)

Extensions (optional)

Custom node and communication-channel bundles run in the separate extension runner and are disabled by default. Enabling them requires this source checkout because the runner image is built locally; the published Moira image does not import or package bundle code.

mkdir -p extensions
cp -R examples/extensions/webhook-notify extensions/
printf '\nMOIRA_EXTENSION_RUNNER_URL=http://moira-extension-runner:9110\n' >> .env
docker compose --profile extensions up -d --build

Before starting the example, replace both placeholder network permissions and fill its per-user settings. The example contributes both a workflow action node and an ordinary notification channel. See Self-hosting: Enable extensions and Writing an Extension for the complete installation, SDK, permission and failure contracts. npm run test:docker-extensions verifies the default-off profile and read-only bundle mount.

Testing

The integration/API/E2E suites run against a local Docker container, configured by .env.local. Copy the template once before running them (or before npm run docker:restart):

cp .env.local.example .env.local   # then set BETTER_AUTH_SECRET
npm test              # All tests
npm run test:unit     # Unit tests only (no container needed)
npm run test:e2e      # E2E tests

Code Quality

npm run fix                   # ESLint + Prettier fix all files

Configuration in .env (copy from .env.example):

• MOIRA_PORT: External access port (default 8080)
• MOIRA_HOST: Public host:port the instance is served on (default localhost:8080)
• STATIC_ARTIFACTS_DOMAIN: Wildcard subdomain base for published artifacts
• BETTER_AUTH_SECRET: generated and persisted on first start when empty; set it explicitly only when you want to manage the auth signing secret yourself
• Database: SQLite at ./data/moira.db (bind-mounted, persists across restarts)
• Admin: ADMIN_EMAIL, ADMIN_PASSWORD (auto-generated on first start if unset)

Authentication

MCP Moira uses Better Auth with OAuth 2.1 for centralized authentication.

Browser Access:

• Email/password login at http://localhost:8080/login
• GitHub/Google OAuth (saas mode only; disabled in self-host)
• Better Auth UI components (Tailwind + shadcn/ui)

MCP Clients:

• OAuth 2.1 authorization code flow
• HTTP 401 triggers OAuth discovery
• Dynamic Client Registration (DCR) supported
• Access token required for all MCP tool calls

Protected:

• All MCP tools require authentication
• All API routes (/api/) require authentication (except /api/auth/)
• Centralized protection via middleware (no manual checks)

Testing:

docker compose up -d
# Access:        http://localhost:8080/login
# MCP Inspector: http://localhost:8080/mcp

See docs/AUTHENTICATION.md for complete setup and OAuth flow details.

MCP Configuration

Point your MCP client (e.g. Claude Code) at your running instance:

{
  "mcpServers": {
    "moira-local": { "url": "http://localhost:8080/mcp" }
  }
}

Replace localhost:8080 with your own host/port (MOIRA_HOST) if you serve Moira on a different address.

Representative Node Examples

The examples below show common graph patterns; they are not the complete node-type inventory. See the Nodes reference for every supported type and its current contract, including automatic note operations and file materialization.

Start Node

{
  "type": "start",
  "id": "start",
  "connections": { "default": "next-node-id" }
}

Agent Directive Node

{
  "type": "agent-directive",
  "id": "task",
  "directive": "Task instruction",
  "completionCondition": "Success criteria",
  "inputSchema": {/* JSON Schema */},
  "connections": { "success": "next-node-id" }
}

Condition Node

{
  "type": "condition",
  "id": "check",
  "condition": {
    "operator": "gte",
    "left": { "contextPath": "score" },
    "right": 8
  },
  "connections": {
    "true": "success-path",
    "false": "failure-path"
  }
}

User Notification Node