Happy MCP

Happy MCP 是一个独立的远程控制网关。外部 AI 通过 OAuth 连接 MCP；网关只把管理员启用的 Happy 机器、目录和操作暴露出去，并在敏感操作前执行独立 LLM 审核。

本仓库不依赖 Happy monorepo，也不要求修改 happy-agent、happy-cli、happy-server 或 relay 源码。src/happy-adapter/ 内置了最小 Happy HTTP、WebSocket、加密和 RPC 适配层，运行时使用已有 Happy 账户凭据与现有 relay。

完整实现、工具目录和运行语义见 ARCHITECTURE.md。

当前部署

• MCP：https://tpt-vps01.mcmdo.com/mcp

• OAuth issuer：https://tpt-vps01.mcmdo.com

• 本机管理面板：http://127.0.0.1:3021/

• Happy relay：http://127.0.0.1:3005

• 运行数据：/home/hlife/happy-mcp-data

• Happy 凭据：/home/hlife/.happy/agent.key

• 用户服务：happy-mcp.service

管理面板只绑定 loopback。运行数据、管理员密码、OAuth 客户端、审核模型配置、API key、任务和审核日志均位于仓库外，不会提交到 Git。

Related MCP server: Shellgate

安装

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

cd /home/hlife/happy-mcp
pnpm install
pnpm test
pnpm build

本机运行：

HAPPY_MCP_PUBLIC_URL=https://tpt-vps01.mcmdo.com \
HAPPY_MCP_DATA_DIR=/home/hlife/happy-mcp-data \
HAPPY_SERVER_URL=http://127.0.0.1:3005 \
HAPPY_HOME_DIR=/home/hlife/.happy \
node dist/index.mjs

完整环境变量示例见 .env.example，systemd 示例见 deploy/happy-mcp.service。

配置复用

服务继续读取 HAPPY_MCP_DATA_DIR 指定的数据目录。只要同时保留：

• happy-mcp.sqlite

• storage.key

• admin-password.txt

原有机器 allowlist、批准目录、自然语言规则、审核 API Base URL、模型名、API 风格、双重审核开关、加密 API key、OAuth 客户端和任务记录都会原样复用。不要只迁移 SQLite 而遗漏 storage.key，否则加密字段无法解密。

安全模型

机器默认禁用。管理员必须在本机面板中设置批准目录、自然语言规则并显式启用机器。

默认双重审核：

1. 第一 reviewer 根据全局规则、机器规则和请求的具体效果作出结构化决定。

2. 第一 reviewer 放行后，第二 reviewer 进行对抗复核。

3. 审核配置缺失、超时、HTTP 错误、输出超限或 JSON schema 不合法时失败关闭。

OAuth 和 LLM 审核不是操作系统沙箱。远端 Agent 或 shell 最终拥有 Happy 进程所属用户的权限；敏感机器仍应使用低权限用户、容器或 VM。

验证

pnpm typecheck
pnpm test
pnpm build
pnpm smoke

pnpm smoke 会真实走 OAuth、PKCE、MCP 初始化和工具发现，并撤销测试客户端。它需要正在运行的本机服务以及管理员密码文件。

来源

src/happy-adapter/ 派生自 MIT 许可的 Happy Coder 客户端实现，归属说明见 NOTICE。