# SAYA Nexus

Self-hosted hub that connects your mailboxes to AI agents over the [Model Context Protocol](https://modelcontextprotocol.io), with explicit per-mailbox permissions and your approval on every outbound email.

Each installation has one owner. There is no signup page. You create that owner from the command line, connect your own mailboxes, and issue a separate token for each agent.

Laravel 13 · React 19 · Tailwind/shadcn · MySQL or MariaDB · official PHP MCP SDK. A production server needs PHP and MySQL only: no Node runtime, Redis, queue workers, or WebSockets.

## What you can do

- Connect generic IMAP/SMTP mailboxes, plus Gmail and Microsoft 365 when you configure OAuth.
- Give each agent its own token and turn on only the abilities it needs, per mailbox. A new agent can see nothing.
- Let an agent read, search, draft, and request a send. Sending waits until you approve that exact message.
- Keep an audit log of owner actions and agent tool calls. Mailbox passwords stay encrypted and are never returned to the browser or to an agent.

## Requirements

- PHP 8.3+ (8.4 used in development) with `openssl`, `pdo_mysql`, `mbstring`, `intl`, `fileinfo`, `iconv`, `dom`, `sodium`, `curl`
- Composer 2
- MySQL 8+ or MariaDB 10.6+
- Node.js 20+ only on the machine that builds the frontend

The web server must be able to open outbound TLS connections to your mail hosts (IMAP 993, SMTP 465 or 587).

## Quick start

```bash
git clone https://github.com/AbdalhalimSy/nexus.git
cd nexus
composer install
cp .env.example .env
php artisan key:generate
mysql -uroot -e "CREATE DATABASE saya_nexus CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
php artisan migrate
php artisan nexus:owner you@example.com
npm ci && npm run build:herd
php artisan serve --host=127.0.0.1 --port=8020
```

Dashboard: `http://127.0.0.1:8020` · MCP endpoint: `http://127.0.0.1:8020/mcp`

`nexus:owner` prompts for a password. Run the test suite against its own database before you point this at real mail. See [local setup](docs/LOCAL_SETUP.md).

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Local setup and tests](docs/LOCAL_SETUP.md)
- [MCP client setup](docs/MCP_CLIENT_SETUP.md), including the OAuth limitation
- [Security](docs/SECURITY.md)
- [Shared hosting](docs/SHARED_HOSTING_COMPATIBILITY.md)
- [Deployment](docs/DEPLOYMENT.md)

## MCP in one minute

Create an agent in the dashboard, copy the token once, and send it as a bearer token:

```bash
curl -s https://nexus.example.com/mcp \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

Clients that accept a custom `Authorization` header work. Hosted connectors that only offer OAuth sign-in do not: SAYA Nexus does not implement MCP OAuth. Details and the tool list are in [MCP client setup](docs/MCP_CLIENT_SETUP.md).

## Security

Mailbox credentials and agent tokens are secrets. Read [Security](docs/SECURITY.md) before you expose an install to the internet. Report a vulnerability privately through [GitHub Security Advisories](https://github.com/AbdalhalimSy/nexus/security/advisories/new).

## License

[MIT](LICENSE)