阿尔法

Name: 阿尔法
Author: Aqualia

作者：Aqualia45 星标更新：2025-10-30

项目介绍

<p align="center"> <img src="assets/alph-banner.svg" alt="Alph banner" width="720" /> </p> <p align="center"> <b>Alph</b> — 使用一条命令配置您的AI代理的MCP服务器。本地优先，原子操作，无压力。 </p> <p align="center"> <a href="https://www.npmjs.com/package/@aqualia/alph-cli"><img alt="npm" src="https://img.shields.io/npm/v/@aqualia/alph-cli"></a> <a href="https://www.npmjs.com/package/@aqualia/alph-cli"><img alt="downloads" src="https://img.shields.io/npm/dm/@aqualia/alph-cli"></a> <a href="https://github.com/Aqualia/Alph"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Aqualia/Alph?style=social"></a> <a href="./LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-green.svg"></a> </p>

您熟悉的难题

每个AI代理都使用不同的配置语言。Cursor希望在~/.cursor/mcp.json中找到JSON。Claude期望它在./.mcp.json中。Gemini使用~/.gemini/settings.json。一个拼写错误就可能破坏一切。没有备份，没有验证。手动编辑容易出错且耗时。

您可能遇到过这种情况：复制粘贴服务器URL，修复括号不匹配的问题，并重启IDE，希望这次能成功。本应只需30秒的操作却变成了30分钟的调试会话。

为什么选择Alph？

现代AI代理使用MCP（模型上下文协议），但连接它们仍然意味着需要手动编辑脆弱的本地配置文件，针对每种工具和操作系统。Alph让这一切变得轻松：它能够检测已安装的代理，验证更改，执行带有时间戳备份的原子写入，并提供即时回滚——所有这些都不涉及任何网络流量。

将Alph视为您的AI开发工具通用遥控器。指向您的MCP服务器（本地或远程），选择您的代理，然后完成。

示例

快速示例

# 通过一条命令将Cursor连接到您的MCP服务器
alph setup --mcp-server-endpoint https://api.example.com/mcp --bearer your-key --agents cursor

# ✅ 检测Cursor安装
# ✅ 验证配置
# ✅ 创建时间戳备份
# ✅ 原子写入配置
# ✅ 验证一切正常工作

对比

<table> <tr> <th>😰 手动方式（易出错）</th> <th>😌 Alph方式（无懈可击）</th> </tr> <tr> <td>

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

手动编辑： 存在语法错误的风险

手动重启： 希望它能工作 🤞

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

❌ 无验证
❌ 无备份
❌ 易于破坏

</td> <td>

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

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

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

</td> </tr> </table>

交互式演示

Alph演示

快速向导运行：检测代理 → 选择传输方式 → 写入配置 → 验证 → 完成。

30秒内尝试 ⚡

# 不需安装 - 现在就试一试
npx @aqualia/alph-cli@latest

# 或立即连接到您的MCP服务器：
npx @aqualia/alph-cli@latest setup \
  --mcp-server-endpoint https://your-server.com/mcp \
  --bearer your-api-key \
  --agents cursor,claude

要求：Node.js ≥ 18

永久安装（如果您喜欢）

# 全局安装以重复使用
npm install -g @aqualia/alph-cli

# 然后只需运行：
alph

支持的AI代理

Alph默认检测并配置以下代理：

Gemini CLI (~/.gemini/settings.json)
Cursor
Claude Code
Windsurf
Codex CLI
Kiro (~/.kiro/settings/mcp.json)

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

代理	macOS	Linux	Windows	HTTP	SSE	STDIO
Gemini CLI	✅	✅	✅	✅	✅	✅
Cursor	✅	✅	✅	✅	✅	✅
Claude Code	✅	✅	✅	✅	✅	✅
Windsurf	✅	✅	✅	✅	✅	✅
Codex CLI	✅	✅	❌	✅	✅	✅
Kiro	✅	✅	✅	✅	✅	✅

MCP传输基础 — 主机/代理通过STDIO（本地）、HTTP或SSE（流式HTTP）连接到服务器。Alph支持这三种方式，并允许您根据代理选择最佳方式。

兼容性说明

Windows上的Codex CLI：由于Codex CLI在Windows上处理进程启动和环境变量时存在上游兼容性问题，目前不支持。这不是Alph特有的限制，而是Codex CLI实现中的已知问题。Codex存储库中正在积极跟踪多个问题，包括#2555，#3311和#3408。我们建议在macOS或Linux上使用Codex CLI以获得最佳体验，或者考虑在Windows上使用其他代理，如Cursor或Windsurf。

使用方法

1) 交互式（推荐）

# 检测代理，引导传输方式选择，原子写入配置并创建备份
alph
# 或
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，Alph可以自动安装本地工具（通过--no-install选项退出）并在写入任何配置之前进行健康检查。

# 使用STDIO而不自动安装工具
alph setup --transport stdio --no-install

# 选择特定的安装程序（npm|brew|pipx|cargo|auto）
alph setup --transport stdio --install-manager npm

# 通过环境控制原子写入策略
ALPH_ATOMIC_MODE=copy alph setup --mcp-server-endpoint https://... --agents gemini

快速开始（与AskHuman MCP服务器）

AskHuman是一个远程MCP服务器。使用Alph将您的本地代理连接到个人AskHuman端点只需几秒钟。

# 一次性配置AskHuman（远程MCP服务器）用于多个代理
# 将YOUR_SERVER_ID替换为AskHuman → 您的MCP服务器中显示的ID
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>）并生成访问密钥（如果启用了身份验证）。
支持HTTP和SSE传输方式；如果主机/代理偏好流，则选择--transport sse并使用.../api/mcp/<id>/sse端点。

默认的安全性和可靠性

本地优先：Alph仅在本地文件上操作；配置/移除期间无网络请求。
带有时间戳备份的原子写入和验证；如果出现问题，快速回滚。
输出中删除秘密（例如，承载令牌）。

命令参考（简洁版）

alph setup [options]
  --mcp-server-endpoint <url>  MCP服务器端点URL
  --bearer [token]             授权承载令牌（可选）
  --transport <type>           http | sse | stdio
  --command <cmd>              STDIO传输命令
  --cwd <path>                 STDIO命令的工作目录
  --args <list>                STDIO命令的逗号分隔参数列表
  --env <list>                 环境变量（KEY=VALUE）
  --headers <list>             HTTP头（KEY=VALUE）
  --timeout <ms>               命令超时
  --install-manager <mgr>      npm | brew | pipx | cargo | auto
  --atomic-mode <mode>         auto | copy | rename
  --no-install                 跳过STDIO工具的自动安装
  --agents <list>              过滤器（例如gemini,cursor）
  --dir <path>                 自定义配置根目录
  --dry-run                    预览更改（不写入）
  --name <id>                  MCP服务器名称/ID

alph status [options]          显示检测到的代理和配置的服务器
  --dir <path>                 包括适用的项目级配置（例如Claude）

alph remove [options]
      --server-name <name>         要移除的MCP服务器名称
      --agents <list>              过滤要修改的代理
      --dir <path>                 自定义配置根目录
      --scope <auto|global|project|all>  移除范围（例如Claude）
      --dry-run                    预览移除（不写入）
      -y, --yes                    跳过确认
      -i, --interactive            移除向导
      --no-backup                  移除前不备份（高级）

故障排除（快速解决）

似乎没有任何变化 → 使用--dry-run重新运行以确认检测和计划的写入；然后不带此选项运行。
未检测到代理 → 确保代理已安装并且其配置位于默认位置（参见代理文档在docs/agents）。
缺少STDIO工具 → 添加--install-manager npm（或brew|pipx|cargo）或使用--no-install如果您想自行管理。

文档

用户指南 → USER_GUIDE.md（高级设置，更多示例）
架构 → ARCHITECTURE.md（执行流程及结构）
安全性 → SECURITY.md（秘密处理，备份，回滚）
故障排除 → TROUBLESHOOTING.md
贡献 → CONTRIBUTING.md

社区和支持

提交问题：https://github.com/Aqualia/Alph/issues
功能请求：https://github.com/AAqualia/Alph/issues/new?template=feature_request.yml
报告错误：https://github.com/Aqualia/Alph/issues/new?template=bug_report.yml
行为准则：贡献者公约v2.1。联系：hello@aqualia.ie。

许可证

MIT — 查看LICENSE。