Alph banner

Alph — Configure MCP servers for your AI agents in one command. Local-first, atomic, and stress-free.

npm GitHub stars MIT License

## The Problem You Know Too Well Every AI agent speaks a different configuration language. Cursor wants JSON in `~/.cursor/mcp.json`. Claude expects it in `./.mcp.json`. Gemini uses `~/.gemini/settings.json`. One typo breaks everything. No backups. No validation. Manual editing is error-prone and time-consuming. You've probably been there: copy-pasting server URLs, fixing bracket mismatches, and restarting your IDE hoping it works this time. What should take 30 seconds becomes a 30-minute debugging session. ## Why Alph? Modern AI agents speak **MCP (Model Context Protocol)**, but wiring them up still means hand-editing fragile local config files per tool and per OS. Alph makes that painless: it **detects** installed agents, **validates** changes, performs **atomic writes** with **timestamped backups**, and gives you **instant rollback** — all without sending any network traffic. > Think of Alph as the **universal remote for your AI developer tools**. Point it at your MCP server (local or remote), pick your agent(s), and you’re done. --- ## Demo ### Quick Example ```bash # Connect Cursor to your MCP server in one command alph setup --mcp-server-endpoint https://api.example.com/mcp --bearer your-key --agents cursor # ✅ Detects Cursor installation # ✅ Validates configuration # ✅ Creates timestamped backup # ✅ Writes config atomically # ✅ Verifies everything works ``` ### Before vs After
😰 Manual Way (Error-Prone) 😌 Alph Way (Bulletproof)
**Find config file:** `~/.cursor/mcp.json` **Edit by hand:** Risk syntax errors **Manual restart:** Hope it works 🤞 ```json { "mcpServers": { "myserver": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer sk-..." } } } } ``` ❌ No validation ❌ No backups ❌ Easy to break **One command:** Works everywhere ```bash alph setup \ --mcp-server-endpoint https://api.example.com/mcp \ --bearer sk-your-key \ --agents cursor ``` ✅ Auto-detects agents ✅ Creates backups ✅ Validates config ✅ Atomic writes ✅ Auto-rollback on error ✅ **Done!** 🎉
### Interactive Demo ![Alph Demo](demo-alph.gif) *A quick wizard run: detect agents → choose transport → write configs → validate → done.* ## Try in 30 Seconds ⚡ ```bash # No installation needed - try it now npx @aqualia/alph-cli@latest # Or connect to your MCP server instantly: npx @aqualia/alph-cli@latest setup \ --mcp-server-endpoint https://your-server.com/mcp \ --bearer your-api-key \ --agents cursor,claude ``` **Requirements**: Node.js ≥ 18 ### Permanent Installation (if you like it) ```bash # Global install for repeated use npm install -g @aqualia/alph-cli # Then just run: alph ``` --- ## Supported AI Agents Alph detects and configures these agents out of the box: * **Gemini CLI** (`~/.gemini/settings.json`) * **Cursor** * **Claude Code** * **Windsurf** * **Codex CLI** * **Kiro** (`~/.kiro/settings/mcp.json`) **Compatibility Matrix (OS × Transport)** | Agent | macOS | Linux | Windows | HTTP | SSE | STDIO | | ----------- | :---: | :---: | :-----: | :--: | :-: | :---: | | Gemini CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Cursor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Claude Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Windsurf | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Codex CLI | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | | Kiro | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | > **MCP Transports 101** — Hosts/agents connect to servers via **STDIO** (local), **HTTP**, or **SSE** (streaming HTTP). Alph supports all three and lets you pick the best per agent. --- ## Compatibility Notes **Codex CLI on Windows**: Currently not supported due to upstream compatibility issues with Codex CLI's process spawning and environment variable handling on Windows. This is not an Alph-specific limitation but rather a known issue in the Codex CLI implementation. Multiple issues are actively tracked in the Codex repository, including [#2555](https://github.com/openai/codex/issues/2555), [#3311](https://github.com/openai/codex/issues/3311), and [#3408](https://github.com/openai/codex/issues/3408). We recommend using Codex CLI on macOS or Linux for the best experience, or consider alternative agents like Cursor or Windsurf on Windows. --- ## Usage ### 1) Interactive (recommended) ```bash # Detects agents, guides transport choice, writes configs atomically with backups alph # or alph setup ``` * No flags needed: the wizard handles detection, preview, and safe writes. ### 2) Non-interactive (one-liner) ```bash alph setup \ --mcp-server-endpoint https://www.askhuman.net/api/mcp/YOUR_SERVER_ID \ --bearer YOUR_ASKHUMAN_ACCESS_KEY \ --agents gemini,cursor ``` * Add `--dry-run` to preview changes without touching files. ### 3) STDIO tools (local servers) For STDIO, Alph can auto-install the local tool (opt-out with `--no-install`) and run health checks before writing any config. ```bash # Use STDIO without auto-installing the tool alph setup --transport stdio --no-install # Prefer a specific installer (npm|brew|pipx|cargo|auto) alph setup --transport stdio --install-manager npm # Control the atomic write strategy via env ALPH_ATOMIC_MODE=copy alph setup --mcp-server-endpoint https://... --agents gemini ``` ## Quick Start (with **AskHuman** MCP server) AskHuman is a remote MCP server. Use Alph to connect your local agents to your personal AskHuman endpoint in seconds. ```bash # Configure AskHuman (remote MCP server) for multiple agents in one go # Replace YOUR_SERVER_ID with the ID shown in AskHuman → Your MCP Server alph setup \ --mcp-server-endpoint https://www.askhuman.net/api/mcp/YOUR_SERVER_ID \ --bearer YOUR_ASKHUMAN_ACCESS_KEY ``` * **Where to find these values**: In the AskHuman dashboard (Your MCP Server), copy your endpoint (`.../api/mcp/`) and generate an access key if auth is enabled. * Works with **HTTP** and **SSE** transports; choose `--transport sse` and use the `.../api/mcp//sse` endpoint if your host/agent prefers streams. --- ## Safety & Reliability by Default * **Local-first**: Alph operates purely on local files; no network requests during configure/remove. * **Atomic writes** with **timestamped backups** and **validation**; fast **rollback** if anything looks off. * **Secrets redacted** in output (e.g., bearer tokens). --- ## Command Reference (concise) ```text alph setup [options] --mcp-server-endpoint MCP server endpoint URL --bearer [token] Authorization bearer token (optional) --transport http | sse | stdio --command Command for stdio transports --cwd Working directory for stdio command --args Comma-separated args for stdio command --env Env vars (KEY=VALUE) --headers HTTP headers (KEY=VALUE) --timeout Command timeout --install-manager npm | brew | pipx | cargo | auto --atomic-mode auto | copy | rename --no-install Skip auto-install for STDIO tools --agents Filter (e.g. gemini,cursor) --dir Custom config root --dry-run Preview changes (no writes) --name Name/ID for the MCP server alph status [options] Show detected agents and configured servers --dir Include project-level configs where applicable (e.g., Claude) alph remove [options] --server-name MCP server name to remove --agents Filter agents to modify --dir Custom config root --scope Scope for removal where supported (e.g., Claude) --dry-run Preview removal (no writes) -y, --yes Skip confirmation -i, --interactive Removal wizard --no-backup Do not back up before removal (advanced) ``` --- ## Troubleshooting (quick hits) * **Nothing seems to change** → Re-run with `--dry-run` to confirm detection and planned writes; then run without it. * **Agent not detected** → Ensure the agent is installed and its config is in the default location (see agent docs in `docs/agents`). * **STDIO tool missing** → Add `--install-manager npm` (or `brew|pipx|cargo`) or run with `--no-install` if you want to manage it yourself. --- ## Documentation * **User Guide** → `USER_GUIDE.md` (advanced setups, more recipes) * **Architecture** → `ARCHITECTURE.md` (execution flows & structure) * **Security** → `SECURITY.md` (secret handling, backups, rollback) * **Troubleshooting** → `TROUBLESHOOTING.md` * **Contributing** → `CONTRIBUTING.md` --- ## Community & Support * Open issues: [https://github.com/Aqualia/Alph/issues](https://github.com/Aqualia/Alph/issues) * Feature request: [https://github.com/Aqualia/Alph/issues/new?template=feature\_request.yml](https://github.com/Aqualia/Alph/issues/new?template=feature_request.yml) * Bug report: [https://github.com/Aqualia/Alph/issues/new?template=bug\_report.yml](https://github.com/Aqualia/Alph/issues/new?template=bug_report.yml) * Code of Conduct: Contributor Covenant v2.1. Contact: [hello@aqualia.ie](mailto:hello@aqualia.ie). ## License MIT — see [LICENSE](./LICENSE). ---