AI导哈

AI代理MCP服务器配置工具

Alph是一款用于为AI代理配置MCP服务器的工具，支持本地优先、原子操作和无压力配置。

  • by Aqualia
  • TypeScript
  • 本地部署
  • 70 星标
  • 更新于
在 GitHub 查看 Aqualia/Alph

使用说明

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

你太清楚的问题

每个AI代理都使用不同的配置语言。游标需要JSON ~/.cursor/mcp.json克劳德期待着它的到来 ./.mcp.json双子座使用 ~/.gemini/settings.json一个错别字就会毁掉一切。没有备份。没有验证。手动编辑容易出错且耗时。

你可能已经经历过：复制粘贴服务器URL，修复括号不匹配，重新启动IDE，希望这次能正常工作。应该需要30秒的时间变成了30分钟的调试会话。

为什么是阿尔法？

现代AI代理说话 MCP（模型上下文协议），但将它们连接起来仍然意味着手动编辑每个工具和每个操作系统的脆弱的本地配置文件。阿尔法让这一切变得无痛：它 检测 已安装的代理， 验证 更改、执行 原子写入 和 带时间戳的备份，并给你 即时回滚 --所有这些都不发送任何网络流量。

将阿尔法视为 为您的AI开发工具提供通用遥控器。将其指向您的MCP服务器（本地或远程），选择您的代理，即可完成。

演示

快速示例

# 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

之前vs之后

😰 Manual Way (Error-Prone) 😌 Alph Way (Bulletproof)

查找配置文件： ~/.cursor/mcp.json

手工编辑： 风险语法错误

手动重启： 希望它能奏效🤞

{
  "mcpServers": {
    "myserver": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-..."
      }
    }
  }
}

❌ 无验证
❌ 无备份
❌ 容易折断

一个命令： 适用于所有地方

alph setup \
  --mcp-server-endpoint https://api.example.com/mcp \
  --bearer sk-your-key \
  --agents cursor

✅ 自动检测代理
✅ 创建备份
✅ 验证配置
✅ 原子写入
✅ 错误时自动回滚
✅ 完成！ 🎉

交互式演示

快速运行向导：检测代理→ 选择交通工具→ 写入配置→ 验证→ done.

30秒内尝试⚡

# 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

需求：Node.js≥18

永久安装（如果你喜欢的话）

# Global install for repeated use
npm install -g @aqualia/alph-cli

# Then just run:
alph

支持的AI代理

阿尔法可以开箱即用地检测和配置这些代理：

  • Gemini CLI (~/.gemini/settings.json)
  • 光标
  • 克劳德代码
  • 帆板运动
  • Codex CLI
  • 基罗 (~/.kiro/settings/mcp.json)

兼容性矩阵（操作系统×传输）

代理 macOS Linux Windows HTTP SSE STDIO
Gemini CLI ✅ ✅ ✅ ✅ ✅ ✅
光标 ✅ ✅ ✅ ✅ ✅ ✅
克劳德代码 ✅ ✅ ✅ ✅ ✅ ✅
风浪 ✅ ✅ ✅ ✅ ✅ ✅
Codex CLI ✅ ✅ ❌ ✅ ✅ ✅
基罗 ✅ ✅ ✅ ✅ ✅ ✅

MCP运输101 --主机/代理通过以下方式连接到服务器 工作室 （本地）， 超文本传输协议，或 上海证券交易所 （流式HTTP）。阿尔法支持这三种方法，并允许您为每个代理选择最好的。

兼容性说明

Windows上的Codex CLI：由于Codex CLI在Windows上的进程生成和环境变量处理的上游兼容性问题，目前不受支持。这不是特定于字母的限制，而是Codex CLI实施中的一个已知问题。Codex存储库中积极跟踪多个问题，包括 #2555, #3311，以及 #3408。我们建议在macOS或Linux上使用Codex CLI以获得最佳体验，或考虑在Windows上使用Cursor或Windsurf等替代代理。

用法

1） 互动（推荐）

# Detects agents, guides transport choice, writes configs atomically with backups
alph
# or
alph setup
  • 无需标记：向导处理检测、预览和安全写入。

2） 非交互式（单行）

alph setup \
  --mcp-server-endpoint https://www.askhuman.net/api/mcp/YOUR_SERVER_ID \
  --bearer YOUR_ASKHUMAN_ACCESS_KEY \
  --agents gemini,cursor
  • 添加 --dry-run 预览更改而不触摸文件。

3） STDIO工具（本地服务器）

对于STDIO，阿尔法可以自动安装本地工具（选择退出 --no-install)并在写入任何配置之前运行健康检查。

# 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

快速入门（与 AskHuman MCP服务器）

AskHuman是一个远程MCP服务器。使用阿尔法在几秒钟内将您的本地代理连接到您的个人AskHuman端点。

# 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
  • 在哪里可以找到这些值：在AskHuman仪表板（您的MCP服务器）中，复制您的端点(.../api/mcp/<your-id>)如果启用了auth，则生成访问密钥。
  • 使用 超文本传输协议 和 上海证券交易所 运输；选择 --transport sse 并使用 .../api/mcp/<id>/sse 端点（如果您的主机/代理更喜欢流）。

默认安全性和可靠性

  • 本地优先：Alph仅对本地文件进行操作；配置/删除期间没有网络请求。
  • 原子写入 和 带时间戳的备份 和 验证；快 回滚 如果有什么不对劲。
  • 秘密被编辑 在输出中（例如承载令牌）。

命令参考（简明）

alph setup [options]
  --mcp-server-endpoint <url>  MCP server endpoint URL
  --bearer [token]             Authorization bearer token (optional)
  --transport <type>           http | sse | stdio
  --command <cmd>              Command for stdio transports
  --cwd <path>                 Working directory for stdio command
  --args <list>                Comma-separated args for stdio command
  --env <list>                 Env vars (KEY=VALUE)
  --headers <list>             HTTP headers (KEY=VALUE)
  --timeout <ms>               Command timeout
  --install-manager <mgr>      npm | brew | pipx | cargo | auto
  --atomic-mode <mode>         auto | copy | rename
  --no-install                 Skip auto-install for STDIO tools
  --agents <list>              Filter (e.g. gemini,cursor)
  --dir <path>                 Custom config root
  --dry-run                    Preview changes (no writes)
  --name <id>                  Name/ID for the MCP server

alph status [options]          Show detected agents and configured servers
  --dir <path>                 Include project-level configs where applicable (e.g., Claude)

alph remove [options]
      --server-name <name>         MCP server name to remove
      --agents <list>              Filter agents to modify
      --dir <path>                 Custom config root
      --scope <auto|global|project|all>  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)

故障排除（快速点击）

  • 似乎什么都没有改变 → 重新运行 --dry-run 确认检测和计划写入；然后不用它就跑。
  • 未检测到代理 → 确保代理已安装，其配置位于默认位置（请参阅中的代理文档 docs/agents).
  • STDIO工具缺失 → Add --install-manager npm （或 brew|pipx|cargo)或跑步 --no-install 如果你想自己管理。

文档

  • 用户指南 → USER_GUIDE.md （高级设置，更多食谱）
  • 建筑 → ARCHITECTURE.md （执行流程和结构）
  • 安全 → SECURITY.md （秘密处理、备份、回滚）
  • 故障排除 → TROUBLESHOOTING.md
  • 贡献 → CONTRIBUTING.md

社区与支持

许可证

麻省理工学院——见 许可证.

相关 MCP