Content
# 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](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](#self-host-recommended)
below.
- **Moira Cloud (managed)** — a hosted instance with nothing to operate, at
[moira-mcp.com](https://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:
```bash
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](#self-host-recommended) or the in-app docs
at `/docs/` for the full reference.
### Updating / Upgrading
Update a normal self-host installation with the standard Compose commands:
```bash
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](packages/docs/src/content/docs/docs/getting-started/self-hosting.mdx#updating-and-recovery), with a matching [Russian version](packages/docs/src/content/docs/ru/docs/getting-started/self-hosting.mdx#обновление-и-восстановление). Release notes are on the [GitHub Releases](https://github.com/moira-mcp/moira/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:
```bash
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.
```bash
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](packages/docs/src/content/docs/docs/getting-started/self-hosting.mdx#enable-extensions)
and [Writing an
Extension](packages/docs/src/content/docs/docs/guides/writing-extensions.mdx) 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`):
```bash
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
```bash
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:**
```bash
docker compose up -d
# Access: http://localhost:8080/login
# MCP Inspector: http://localhost:8080/mcp
```
See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) for complete setup and OAuth flow details.
### MCP Configuration
Point your MCP client (e.g. Claude Code) at your running instance:
| Server | URL | Purpose |
| ------------- | ------------------------- | ----------------------------- |
| `moira-local` | http://localhost:8080/mcp | Your local self-host instance |
```json
{
"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](packages/docs/src/content/docs/docs/concepts/nodes.mdx) for every supported
type and its current contract, including automatic note operations and file materialization.
### Start Node
```json
{
"type": "start",
"id": "start",
"connections": { "default": "next-node-id" }
}
```
### Agent Directive Node
```json
{
"type": "agent-directive",
"id": "task",
"directive": "Task instruction",
"completionCondition": "Success criteria",
"inputSchema": {/* JSON Schema */},
"connections": { "success": "next-node-id" }
}
```
### Condition Node
```json
{
"type": "condition",
"id": "check",
"cases": [
{
"when": { "operator": "gte", "left": { "contextPath": "score" }, "right": 8 },
"output": "passed"
}
],
"connections": {
"passed": "success-path",
"default": "failure-path"
}
}
```
`cases` are evaluated in authored order; the first case whose `when` holds selects its `output`,
and `default` is taken when none holds.
### User Notification Node
```json
{
"type": "user-notification",
"id": "notify",
"message": "Task completed: {{result}}",
"format": "plain",
"connections": { "default": "next-node-id" }
}
```
The node fans out to the current user's enabled communication channels and never accepts provider,
recipient, or credential fields. The deprecated `telegram-notification` node remains available for
existing Telegram-specific workflows, including exact explicit `chatId` semantics.
### End Node
```json
{
"type": "end",
"id": "end",
"finalOutput": ["result", "score"]
}
```
### Expression Node
```json
{
"type": "expression",
"id": "increment-counter",
"expressions": ["counter = counter + 1"],
"connections": { "default": "next-step" }
}
```
### Teleport Node
```json
{
"type": "teleport",
"id": "teleport-replan",
"directive": "Rewrite the development plan",
"completionCondition": "New plan created",
"hint": "Use when plan needs restructuring",
"connections": { "success": "plan-node" }
}
```
### Subgraph Node
```json
{
"type": "subgraph",
"id": "run-subtask",
"graphId": "subtask-workflow",
"inputMapping": { "parentVar": "subVar" },
"outputMapping": { "subResult": "parentResult" },
"connections": { "success": "next-step" }
}
```
### Lock Node
```json
{
"type": "lock",
"id": "approval-gate",
"reason": "Waiting for user approval before deployment",
"connections": { "unlocked": "next-step" }
}
```
Pauses execution until explicitly unlocked. Sends PIN via Telegram with inline approve button. Unlockable via MCP tool, web UI, or Telegram callback.
## Workflow Format
```json
{
"id": "workflow-id",
"metadata": {
"name": "Workflow Name",
"version": "1.0.0",
"description": "What this workflow does"
},
"nodes": [/* Node definitions */]
}
```
## Templates
Variables processed in `directive`, `completionCondition`, and `message` fields:
- `{{variable}}` - Context variable
- `{{nested.path}}` - Object property access
- `{{executionId}}` - System: current process ID
- `{{workflowId}}` - System: current workflow ID
- `{{runUrl}}` - System: the run's page in the web app
## MCP Tools
```bash
# Workflow Management
list
start {"workflowId": "workflow-id"}
step {"processId": "process-id", "input": "data"}
manage {"action": "create", "workflow": {...}}
manage {"action": "edit", "workflowId": "workflow-id", "changes": {...}}
manage {"action": "get", "workflowId": "workflow-id"}
# Session Information
session {"action": "user"}
session {"action": "executions"}
session {"action": "execution_context", "executionId": "execution-id"}
session {"action": "current_step", "executionId": "execution-id"}
# Execution Locking
lock {"action": "lock", "executionId": "execution-id", "reason": "Awaiting approval"}
lock {"action": "unlock", "executionId": "execution-id", "pin": "123456"}
lock {"action": "status", "executionId": "execution-id"}
lock {"action": "list"}
# User Settings
settings {"action": "get"}
settings {"action": "get", "category": "codespaces"}
settings {"action": "set", "key": "codespaces.idle_timeout_minutes", "value": 60}
settings {"action": "list"}
# Workflow Tokens
token {"action": "upload", "ttlMinutes": 60}
token {"action": "download", "workflowId": "workflow-id", "ttlMinutes": 60}
# User Communication
communication {"action": "send", "message": "The report is ready."}
communication {"action": "attachment-token", "message": "Report", "kind": "document", "filename": "report.pdf", "mimeType": "application/pdf", "sizeBytes": 12000}
# Documentation
help
help {"topic": "tools"}
help {"topic": "step"}
```
## File Structure
```
packages/workflow-engine/ # Core execution engine
packages/mcp-server/ # MCP HTTP server (internal port, behind nginx)
packages/web-backend/ # Express API (internal port, behind nginx)
packages/web-frontend/ # React UI (static build served by nginx)
data/ # SQLite database (moira.db)
workflows/ # Bundled public workflow catalog
docs/ # Technical documentation
```
## Development
All development happens through Docker containers.
```bash
docker compose up -d --build # Build and run the container
npm test # Run all tests
npm run fix # ESLint + Prettier fix
```
**Database**: SQLite at DB_PATH (default: ./data/moira.db)
**Migrations**: Drizzle ORM (`npx tsx scripts/run-migrations.ts`)
**Storage**: Workflows and executions in database with user isolation
## Documentation
**User Documentation**: Served by your running instance at `/docs/` (EN) and `/ru/docs/` (RU), built from `packages/docs` (Starlight).
**Technical Documentation**: `/docs` directory - system reference, API specs, development guides.
**[Project Checklist](docs/PROJECT_CHECKLIST.md)** - mandatory pre-commit checks executed by development workflows.
## Claude Code Commands
Custom slash commands in `/commands` directory. See [commands/README.md](commands/README.md) for installation and usage.
## HTTP Transport
### Architecture
- **Stateless Mode**: Each HTTP request creates new transport, no session storage
- **JSON-RPC 2.0**: MCP protocol over HTTP with proper error handling
- **Direct Tools**: MCP tools integrated in single process
- **Environment Inheritance**: HTTP server environment variables passed to tools
### Endpoints
```http
POST /mcp # JSON-RPC requests (tools calls)
GET /health # Server health check
```
### Environment Variables
```bash
# Required for Telegram integration
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_DEFAULT_CHAT_ID=your_chat_id
# Optional
MCP_PORT=4202 # Internal MCP server port (accessed via nginx proxy)
LOG_LEVEL=info
DEBUG_CONSOLE=true # Console logging for development
WORKFLOWS_DIR=./packages/web-backend/workflows/production
```
## Configuration
MCP server configuration (see [MCP Configuration](#mcp-configuration) for details):
```json
{
"mcpServers": {
"moira-local": {
"url": "http://localhost:8080/mcp",
"type": "http"
}
}
}
```
Environment variables passed via HTTP headers (recommended for HTTP transport).
Alternative: Set environment variables in your `.env` file.
## Code Quality
### ESLint + Prettier
Project uses ESLint with TypeScript support and Prettier for code formatting.
```bash
npm run fix # Auto-fix lint errors and format code
```
**Pre-commit Hook:**
Husky pre-commit hook automatically runs ESLint and Prettier on staged files.
**Configuration:**
- `.eslintrc.json` - ESLint rules (strict for production code, relaxed for tests)
- `.prettierrc` - Prettier formatting rules
- Production code: `any` types are errors, must be properly typed
- Test code: `any` types allowed for flexibility
## Security
### Rate Limiting
Protection against spam and DoS attacks with tiered limits:
- **API routes** (`/api/*`): 100 requests/minute
- **Auth routes** (`/api/auth/*`): 100 requests/minute
- **MCP endpoint** (`/mcp`): 30 requests/minute
Exceeded limits return HTTP 429 Too Many Requests.
### Data Size Limits
Protection against oversized payloads:
- **Workflow JSON**: max 5MB
- **Execution context**: max 10MB
Exceeded limits return HTTP 413 Payload Too Large.
### GeoIP Logging
Request logging includes country detection via geoip-lite:
```json
{
"method": "POST",
"path": "/api/workflows",
"ip": "203.0.113.1",
"country": "US",
"duration": 45,
"status": 200
}
```
## Admin Features
### User Management
Admin panel at `/admin/users` provides:
- **User list** with approval, email verification, and blocked status
- **User details** page with sessions, OAuth connections, email history
- **Approve** pending self-host registrations
- **Session management** - revoke individual sessions or all sessions
- **OAuth management** - revoke tokens by provider or all OAuth connections
- **Block/Unblock** users with reason
- **Send verification email** manually
- **Send password reset email** manually
- **Set a temporary password** for an ordinary user when email delivery is unavailable
### Execution Monitoring
The Cloud `multiUserAdmin` capability enables the cross-user panel at `/admin/executions`. It is
server-denied and hidden by the default self-host policy:
- View all user executions
- Filter by user, status
- Search by execution ID or workflow ID
- Inspect execution context and variables
### Email History
Track every email attempt:
- Verification emails
- Password reset emails
- Notifications
- Status (`sent`, `failed`, or log-only `logged`) with error messages
## Email Features
### Email Verification (SaaS)
- Verification email sent on SaaS signup; self-host registration uses
administrator approval instead
- Link expires in 24 hours
- Admin can resend manually
### Password Reset
- With a real SMTP or Brevo provider, the user requests via `/forgot-password`
and receives a reset link
- Link expires in 1 hour
- Without real delivery, the reset form and email-send actions report the
capability as unavailable; an administrator can set a temporary password for
an ordinary user and require replacement at the next login
### Email Provider
Configured via environment variables:
```bash
EMAIL_PROVIDER=smtp # smtp, brevo, auto, none, or explicit test sink
EMAIL_FROM=noreply@domain # Required for real delivery
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_REQUIRE_TLS=true
# SMTP_USER and SMTP_PASSWORD are optional, but must be supplied together
```
Real delivery supports generic SMTP and Brevo. With `EMAIL_PROVIDER=auto` (or
unset), a complete SMTP configuration takes precedence and a legacy
`BREVO_API_KEY` plus `EMAIL_FROM` configuration remains supported. The explicit
`test` provider logs messages and is never advertised as real delivery.
## Documentation Map
Where things are documented. After changing code, find the area below and update
the matching file in the same change.
### Public docs — MDX shells plus MCP-owned portable help
Rendered pages live under `packages/docs/src/content/docs/docs/` (EN) and
`packages/docs/src/content/docs/ru/docs/` (RU). Runtime-visible topics keep their semantic Markdown
under `packages/mcp-server/src/help/content/`, with Russian counterparts under `…/content/ru/`.
Each localized MDX shell imports its matching source through the MCP package. The `help` tool
discovers and reads the English sources directly; pages with an interactive insertion compose the
same authored before/after sections in runtime and public presentation. The special `tools` topic is
listed alongside those file-backed topics and renders directly from the typed MCP contract.
| Area | Covers | Path |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------ |
| Getting started | Introduction (agent-first), quickstart, tutorial on the learning flows, which ready flow to use, self-hosting | `getting-started/` |
| Concepts | Workflows, nodes, templates, notes, playbooks, artifacts | `concepts/` |
| Guides | Writing directives, creating & editing workflows, reading a flow and a run, the overview of runs, extensions | `guides/` |
| Reference | Tools, input schema, magic variables, condition operators, validation, workflow catalog | `reference/` |
| Integration | MCP clients, Claude Code, agent guide, Telegram setup, troubleshooting | `integration/` |
| Patterns | Branching, validation loop, escalation, subagent review, workspace, and more | `patterns/` |
### Internal docs — `docs/`
For contributors working on the codebase (implementation detail, not end-user docs).
| File | Covers | Path |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Development setup | Build, Docker, local dev, project structure | `docs/DEVELOPMENT.md` |
| Testing | Test types, runner, fixtures, antipatterns | `docs/TESTING.md` + `docs/testing/` |
| API | Backend & admin HTTP API reference | `docs/API.md` |
| System architecture | Engine, storage, MCP transport, handlers, validation | `docs/SYSTEM.md` |
| Authentication | Better Auth, OAuth 2.1, API tokens | `docs/AUTHENTICATION.md` |
| Web UI | Frontend architecture, components | `docs/WEB-UI.md` |
| Audit system | Audit logging design | `docs/AUDIT-SYSTEM.md` |
| Workflows | Workflow authoring, tools, catalog | `docs/WORKFLOW.md`, `docs/WORKFLOWS.md`, `docs/WORKFLOW-TOOLS.md` |
| Design system | UI design tokens and components | `docs/DESIGN-SYSTEM.md` |
| Documentation style | How to write internal **and** public docs | `docs/DOCUMENTATION-STYLE-GUIDE.md` |
| Logging | Structured logging conventions | `docs/LOGGING.md` |
| Codespaces | GitHub authorization, persistent lifecycle, MCP tools, website management, readiness/metrics/kill switches, isolation | `docs/CODESPACES.md` |
| Issue management | GitHub issue conventions | `docs/ISSUE-MANAGEMENT.md` |
| Architecture decisions | ADRs (licensing, OSS model, …) | `docs/adr/` |
| Deployment | Environment variables, restart procedures | `docs/deployment/` |
| Legal | License/legal notes | `docs/legal/` |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the PR flow, DCO sign-off, and how
releases are automated (Conventional Commits → semantic-release → versioned GHCR
image). For upgrading a self-host instance, see [Updating / Upgrading](#updating--upgrading).
## License
[Apache License 2.0](LICENSE)
Connection Info
You Might Also Like
No recommendations available