Happy MCP

Happy MCP 是安装版 happy-agent 的外接安全桥。外部 AI 通过 OAuth 调用 MCP；MCP 在管理员机器策略和独立 LLM 审查通过后，以非交互子进程方式执行与人类相同的 happy-agent CLI 命令。

MCP client -> OAuth -> machine/path policy -> LLM review -> happy-agent argv

本仓库：

• 不包含 Happy 官方源码；
• 不导入 happy-agent、happy-cli、happy-server 或 relay 内部模块；
• 不实现 Happy 的 REST、WebSocket、加密或 RPC 协议；
• 不要求修改任何 Happy 官方代码；
• 只依赖管理员已经安装、认证并可正常使用的 happy-agent 可执行文件。

完整工具和运行语义见 ARCHITECTURE.md。

前置条件

happy-agent --version
happy-agent auth status
happy-agent machines --json

三条命令必须在运行 MCP 的同一 OS 用户和环境中成功。MCP 不接管 Happy 登录，也不保存 Happy 账户凭据。

安装

要求 Node.js 20 以上和 pnpm 10.11。

cd /path/to/happy-mcp
pnpm install
pnpm test
pnpm build

启动示例：

HAPPY_MCP_PUBLIC_URL=https://mcp.example.com \
HAPPY_MCP_DATA_DIR=/var/lib/happy-mcp \
HAPPY_AGENT_BIN=/usr/local/bin/happy-agent \
node dist/index.mjs

配置示例见 .env.example，systemd 示例见 deploy/happy-mcp.service。

管理配置

本机管理面板默认绑定 127.0.0.1:3021。管理员在面板中配置：

• 哪些由 happy-agent machines --json 发现的机器允许 MCP 使用；
• 每台机器允许的工作目录；
• 每台机器的自然语言放行规则；
• LLM 审查 API、模型、API key、全局规则和双重审核开关；
• OAuth 客户端授权和撤销。

机器默认禁用。审核配置缺失、超时、返回错误或结构化结果不合法时，有副作用的操作失败关闭。

暴露的原生操作

当前只包装原生 happy-agent 已公开的 9 类操作：

• machines --json
• list --json
• status --json
• history --json
• spawn --json
• send --json
• wait
• resume --json
• stop

没有对应原生命令的 abort、permission、goal、shell、文件、kill、archive、delete 和持久 task 不会通过 MCP 暴露。

数据边界

MCP 自己的数据位于 HAPPY_MCP_DATA_DIR：

• happy-mcp.sqlite
• storage.key
• admin-password.txt

其中保存 OAuth、管理员会话、机器策略、审核设置和审核日志。审核 API key 与敏感 OAuth 元数据使用 storage.key 加密。

Happy 登录凭据由 happy-agent 自己管理，不进入 MCP 数据库。

验证

pnpm typecheck
pnpm test
pnpm build
HAPPY_MCP_SMOKE_URL=https://mcp.example.com pnpm smoke

OAuth smoke 会注册临时客户端、完成 PKCE、初始化 MCP、验证工具目录，然后撤销临时客户端并确认 token 失效。