diff --git a/.env.example b/.env.example index a1e4481..450ae0e 100644 --- a/.env.example +++ b/.env.example @@ -1,16 +1,19 @@ -# oh-my-sage 配置文件 +# oh-my-sage 网页版配置文件 +# 复制为 .env 后填写,不要提交 .env。 # ==================== LLM 配置 ==================== -# OpenAI 兼容接口配置 +# OpenAI 兼容接口地址和模型名称,可选服务商见 README「方式二:网页版」 LLM_BASE_URL=https://api.openai.com/v1 -LLM_API_KEY=your_api_key_here LLM_MODEL=gpt-6.1-terra +# 你的 API Key,必填 +LLM_API_KEY= + # 温度(可选,默认 0.7) # LLM_TEMPERATURE=0.7 # ==================== 网关配置 ==================== -# 米家中枢网关地址 -GATEWAY_URL=http://192.168.0.5 +# 米家中枢网关地址,必填,例如 http://192.168.0.5 +GATEWAY_URL= diff --git a/AGENTS.md b/AGENTS.md index a47b699..21d8adc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ npm run build # Production build # MCP development npm run build:mcp # Build MCP server only -npm link # Link oh-my-sage-mcp command globally (local development) +npm link # Link oh-my-sage-mcp globally to test a local build (users install from npm) npm run build:npm # Assemble the publishable oh-my-sage-mcp package in dist/npm # Quality checks @@ -48,7 +48,7 @@ npx tsx --test # Run a single test file **Building**: `npm run build:mcp` outputs to `dist/mcp/mcp/index.js` -**Global command**: `npm link` creates `oh-my-sage-mcp` in PATH +**Global command**: users get `oh-my-sage-mcp` from npm (`npx -y oh-my-sage-mcp` or `npm install -g`); `npm link` is only for testing a local build **Local testing**: `oh-my-sage-mcp` (stdio mode, default) @@ -59,7 +59,9 @@ npx tsx --test # Run a single test file - Local PC service: `deploy/install-local.ps1` (Windows Scheduled Task) or `deploy/install-local.sh` (launchd / systemd --user), loopback only - Private server: `Dockerfile` + `deploy/docker-compose.yml` + `deploy/.env.example` -**Docs layout**: `README.md` is the landing page and index only; deployment details, client config formats and env vars live in `deploy/README.md`. Keep heavy operational detail out of the root README. +**Docs layout**: `README.md` is the landing page and carries the beginner step-by-step for each deployment mode (stdio, local service, Docker, web) plus upgrade/uninstall. `deploy/README.md` holds the reference material: script parameters, every client config shape, env vars and troubleshooting. Do not duplicate parameter tables or env var references into the root README. + +**User-specific values in docs**: never write a concrete gateway IP, server IP, token, API key or passcode into anything a user copies (config blocks, commands, prompts to paste into an AI Agent, `.env.example`). Use placeholders such as `http://<网关 IP>`, `<服务器 IP>`, `<访问密码>`, `<登录码>`; a concrete value may appear only in prose as "例如 …". `.env.example` files leave required values empty so a forgotten field fails loudly instead of pointing at someone else's network. **npm package**: the root `package.json` is the private web app and is never published. `scripts/build-npm-package.mjs` assembles `dist/npm/` as the standalone `oh-my-sage-mcp` package: version from the root `package.json`, dependencies limited to what `dist/mcp` actually requires (shared with the Docker image via `deploy/mcp-runtime-package.mjs`), plus `deploy/install-local.*`, README with absolute image URLs, and LICENSE. `scripts/smoke-npm-package.mjs` installs-and-runs the packed tarball (stdio handshake with 32 tools, HTTP `/healthz` + initialize). CI (`.github/workflows/ci.yml`) runs lint, both typechecks, unit tests, that smoke test on ubuntu/windows/macos × Node 20/22/24, and a Docker build. Release: bump `version` in the root `package.json`, merge, push tag `v`; `.github/workflows/release.yml` publishes via npm trusted publishing (OIDC, no token) and creates the GitHub release. The MCP server reports the package version (`SERVER_VERSION` reads `package.json`), so never hard-code it. @@ -70,7 +72,7 @@ npx tsx --test # Run a single test file "oh-my-sage": { "command": "npx", "args": ["-y", "oh-my-sage-mcp"], - "env": { "GATEWAY_URL": "http://192.168.0.5" } + "env": { "GATEWAY_URL": "http://<网关 IP>" } } } } @@ -138,13 +140,13 @@ import { createGatewayManager } from '@/core/gateway/manager'; // Use @/ alias ## Environment -Copy `.env.example` to `.env`: +Copy `.env.example` to `.env` and fill in the empty values: ```env LLM_BASE_URL=https://api.openai.com/v1 -LLM_API_KEY=your_key LLM_MODEL=gpt-6.1-terra +LLM_API_KEY= # required # LLM_TEMPERATURE=0.7 # optional -GATEWAY_URL=http://192.168.0.5 # example only; there is no built-in default +GATEWAY_URL= # required, e.g. http://192.168.0.5; there is no built-in default ``` ## Comments diff --git a/README.md b/README.md index f3ec5a4..b0c3e94 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ **用说话的方式,创建和修改米家自动化极客版规则** -[![Next.js](https://img.shields.io/badge/Next.js-14-black)](https://nextjs.org/) -[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)](https://www.typescriptlang.org/) +[![npm](https://img.shields.io/npm/v/oh-my-sage-mcp?label=npm)](https://www.npmjs.com/package/oh-my-sage-mcp) [![MCP](https://img.shields.io/badge/MCP-32_tools-6366f1)](#mcp-工具列表) +[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) @@ -21,7 +21,7 @@ Oh My Sage 直接连接局域网里的米家中枢网关。你说想要什么效 - **国内**:腾讯 WorkBuddy、豆包工作、TRAE、Qoder、通义灵码、Kimi Code - **海外**:Claude Code、Cursor、OpenCode、Codex -> 豆包工作这类云端产品只能添加远程地址的连接器,需要用下文的「私有服务器」方式部署,并且要让它能访问到你的服务器地址。 +> 豆包工作这类云端产品只能添加远程地址的连接器,需要用下文的 [私有服务器](#换成私有服务器docker) 方式部署,并且要让它能访问到你的服务器地址。 --- @@ -65,27 +65,38 @@ Oh My Sage 直接连接局域网里的米家中枢网关。你说想要什么效 ### 准备工作 -开始之前,确认这三样都有: - 1. **一台米家中枢网关**,并且已经在米家 App 里开启了「自动化极客版」。 -2. **中枢网关的局域网 IP**,比如 `192.168.0.5`。在米家 App 里打开中枢网关(有多个时选主中枢),点右上角「···」进入设置,找到「自动化极客版」,页面上会显示网关地址。电脑要和网关连在同一个局域网里。 +2. **中枢网关的局域网 IP**,比如 `192.168.0.5`。在米家 App 里打开中枢网关(有多个时选主中枢),点右上角「···」进入设置,找到「自动化极客版」,页面上会显示网关地址。运行 Oh My Sage 的电脑或服务器要和网关在同一个局域网里。 3. **Node.js 20 或更高版本**。没装的话去 [nodejs.org](https://nodejs.org/) 下载 LTS 版本,一路下一步就行。装好后在终端里运行 `node -v`,能看到版本号就说明装好了。 另外,每次连接网关都要一个 **6 位登录码**,也在上面那个「自动化极客版」页面里。到连接的时候再去取:登录码只能用一次,用过(不管成没成功)就作废了。 +### 选一种用法 + +![三种部署方式:stdio、本机常驻、私有服务器](docs/images/deploy.webp) + +| 用法 | 适合 | 登录码 | 怎么装 | +|------|------|--------|--------| +| **AI Agent · 按需启动**(stdio) | 第一次用,先试试看 | AI Agent 每次重启都要重新输 | [方式一](#方式一在-ai-agent-里用mcp),加一段配置就行 | +| **AI Agent · 本机常驻** | 自己一台电脑长期用 | 登录一次,本机所有 AI Agent 共享 | 先走完方式一,再 [换成本机常驻](#换成本机常驻) | +| **AI Agent · 私有服务器**(Docker) | 家里有 NAS,多台电脑共用 | 登录一次,所有电脑共享 | [换成私有服务器](#换成私有服务器docker) | +| **网页版** | 不用 AI Agent,想直接在浏览器里聊 | 网页服务每次启动后输一次 | [方式二](#方式二网页版),需要自己的大模型 API Key | + +拿不准就从第一种开始,以后随时能换,Skill 和用法都不变。 + ### 方式一:在 AI Agent 里用(MCP) -MCP Server 已发布到 npm([`oh-my-sage-mcp`](https://www.npmjs.com/package/oh-my-sage-mcp)),不用下载仓库,AI Agent 会通过 `npx` 自动下载运行。 +MCP Server 已经发布到 npm,包名 [`oh-my-sage-mcp`](https://www.npmjs.com/package/oh-my-sage-mcp)。不用下载仓库,也不用自己编译,AI Agent 会通过 `npx` 自动下载并运行最新版。 #### 最省事:让 AI Agent 帮你装 -打开你的 AI Agent,把下面这段话改好网关地址后整段发给它: +打开你的 AI Agent,把下面这段话里的 `<网关 IP>` 换成你的中枢网关 IP,再整段发给它: ``` 帮我安装这个 MCP Server:https://github.com/allocnode/oh-my-sage -1. 把 npm 包 oh-my-sage-mcp 加进你自己的 MCP 配置,用 npx -y oh-my-sage-mcp 启动,GATEWAY_URL 填 http://192.168.0.5 -2. 运行 npx skills add allocnode/oh-my-sage --skill mijia-automation,把规则 Skill 装给你自己 +1. 把 npm 包 oh-my-sage-mcp 加进你自己的 MCP 配置,用 npx -y oh-my-sage-mcp 启动,环境变量 GATEWAY_URL 填 http://<网关 IP>(如果这里还是尖括号占位符,先问我要网关 IP,不要自己编) +2. 运行 npx skills add allocnode/oh-my-sage --skill mijia-automation -g -y,并用 -a 参数只装给你自己(可选值见 npx skills add --help),不要装给其他 Agent 3. 装完告诉我需要重启什么 ``` @@ -95,7 +106,7 @@ MCP Server 已发布到 npm([`oh-my-sage-mcp`](https://www.npmjs.com/package/o ##### 1. 把它加到 AI Agent 的 MCP 配置里 -在 AI Agent 的设置里找到 MCP(一般叫「MCP」「MCP Servers」或「连接器」),选「手动添加」或「编辑 JSON」,粘贴下面这段,并把 `192.168.0.5` 改成你的中枢网关 IP: +在 AI Agent 的设置里找到 MCP(一般叫「MCP」「MCP Servers」或「连接器」),选「手动添加」或「编辑 JSON」,粘贴下面这段,并把 `<网关 IP>` 换成你的中枢网关 IP(换完类似 `"http://192.168.0.5"`): ```json { @@ -103,7 +114,7 @@ MCP Server 已发布到 npm([`oh-my-sage-mcp`](https://www.npmjs.com/package/o "oh-my-sage": { "command": "npx", "args": ["-y", "oh-my-sage-mcp"], - "env": { "GATEWAY_URL": "http://192.168.0.5" } + "env": { "GATEWAY_URL": "http://<网关 IP>" } } } } @@ -118,10 +129,10 @@ MCP Server 已发布到 npm([`oh-my-sage-mcp`](https://www.npmjs.com/package/o 创建和修改规则时,AI Agent 要参考 `mijia-automation` Skill 里的节点模板和连接规则。在终端里运行: ```bash -npx skills add allocnode/oh-my-sage --skill mijia-automation +npx skills add allocnode/oh-my-sage --skill mijia-automation -g ``` -它会问你要装给哪个 AI Agent,选你正在用的那个就行。不支持 Skill 的 AI Agent,可以把 [SKILL.md](.agents/skills/mijia-automation/SKILL.md) 的内容贴进它的项目规则文件(比如 `AGENTS.md`)。 +`-g` 表示装到用户目录,所有项目都能用;不加的话只装进当前所在的文件夹。安装时会列出你电脑上的 AI Agent,选你正在用的那个就行。不支持 Skill 的 AI Agent,可以把 [SKILL.md](.agents/skills/mijia-automation/SKILL.md) 的内容贴进它的规则文件(比如 `AGENTS.md`)。 ##### 3. 重启 AI Agent @@ -129,10 +140,10 @@ npx skills add allocnode/oh-my-sage --skill mijia-automation ##### 4. 开始对话 -先在米家 App 的「自动化极客版」页面取一个新的登录码,然后对 AI Agent 说: +先在米家 App 的「自动化极客版」页面取一个新的登录码,然后对 AI Agent 说(把 `<登录码>` 换成那 6 位数字): ``` -帮我连接米家网关,登录码是 123456 +帮我连接米家网关,登录码是 <登录码> ``` 连上以后就可以直接提需求: @@ -141,47 +152,125 @@ npx skills add allocnode/oh-my-sage --skill mijia-automation 客厅有人的时候自动开灯,晚上别太亮 ``` -#### 部署方式怎么选 +#### 换成本机常驻 -![三种部署方式:stdio、本机常驻、私有服务器](docs/images/deploy.webp) +按需启动的进程跟着 AI Agent 一起退出,所以每次重启 AI Agent 都要重新输登录码。本机常驻会把 MCP Server 注册成开机登录后自动运行的后台服务,只在本机 `127.0.0.1:3790` 上提供服务,网关登录一次,本机所有 AI Agent 都能共用。 + +![全局安装 oh-my-sage-mcp 并注册为本机后台服务](docs/images/install.webp) -| 方式 | 适合 | 登录码 | -|------|------|--------| -| **stdio**(上面的配置) | 先试试看 | AI Agent 每次重启都要重新输入 | -| **本机常驻** | 自己一台电脑长期用 | 登录一次,所有客户端共享 | -| **私有服务器**(Docker) | 家里有 NAS,多台电脑共用 | 登录一次,所有电脑共享,需要设置访问 token | +1. 全局安装,安装脚本随包一起下载: -本机常驻需要先全局安装,再运行包里自带的安装脚本: + ```bash + npm install -g oh-my-sage-mcp + ``` -![全局安装 oh-my-sage-mcp 并注册为本机后台服务](docs/images/install.webp) +2. 运行安装脚本,把 `<网关 IP>` 换成你的: -```bash -npm install -g oh-my-sage-mcp + ```bash + # Windows(在 PowerShell 里运行,不需要管理员权限) + powershell -ExecutionPolicy Bypass -File "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl "http://<网关 IP>" -# Windows(PowerShell) -pwsh "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl http://192.168.0.5 + # macOS / Linux + bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -g "http://<网关 IP>" + ``` -# macOS / Linux -bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -g http://192.168.0.5 -``` + 看到「已启动:http://127.0.0.1:3790/mcp」就装好了。Windows 注册的是计划任务,macOS 是 launchd,Linux 是 systemd 用户服务,都是登录后自动启动、退出后自动拉起。Windows 命令里的 `-ExecutionPolicy Bypass` 只对这一次运行放开系统默认的脚本限制,不改系统设置;Windows 上的后台服务需要 Node.js 20.6 或更高版本。 + +3. 把 AI Agent 里第 1 步的那段配置换成下面这段(脚本最后也会打印出来,可以直接复制): + + ```json + { + "mcpServers": { + "oh-my-sage": { + "url": "http://127.0.0.1:3790/mcp" + } + } + } + ``` + +4. 重启 AI Agent,按 [第 4 步](#4-开始对话) 连接网关。以后再重启 AI Agent 就不用重新输登录码了。 + +想确认服务在运行,打开 http://127.0.0.1:3790/healthz ,看到 `"ok":true` 就是正常的,`connected` 表示当前是否已登录网关。端口、访问 token 等参数见 [deploy/README.md](deploy/README.md#方式二本机常驻)。 -装完会打印一段配置,把它粘贴到 AI Agent 的 MCP 设置里,替换掉第 1 步的那段即可。以后升级先运行 `npm install -g oh-my-sage-mcp`,再把上面的安装脚本运行一次,它会重启后台服务换上新版本。Docker 部署、全部参数和排障见 [deploy/README.md](deploy/README.md)。 +#### 换成私有服务器(Docker) + +适合家里有 NAS 或一直开着的服务器,几台电脑共用一个网关登录。服务器上要装好 Git 和 Docker(带 Compose),能访问米家中枢网关,也能访问公网的 `miot-spec.org`(校验设备能力时用)。 + +1. 在服务器上下载仓库,复制配置文件: + + ```bash + git clone https://github.com/allocnode/oh-my-sage.git + cd oh-my-sage/deploy + cp .env.example .env + ``` + +2. 编辑 `.env`,必须填这三项: + + ```env + # 米家中枢网关地址 + GATEWAY_URL=http://<网关 IP> + # 访问密码,换成一串足够长的随机字符,可以在服务器上运行 openssl rand -hex 32 生成 + MCP_AUTH_TOKEN=<访问密码> + # 其他电脑访问这台服务器时用的 IP 或域名,多个用英文逗号隔开,不带端口 + MCP_ALLOWED_HOSTS=<服务器 IP> + ``` + + 不填 `MCP_AUTH_TOKEN` 服务会拒绝启动。`MCP_ALLOWED_HOSTS` 漏掉了哪个地址,用那个地址访问就会被拒绝(403)。 + +3. 构建并启动: + + ```bash + docker compose up -d --build + ``` + + 第一次要在服务器上编译,需要几分钟。之后运行 `curl http://<服务器 IP>:3790/healthz`,看到 `"ok":true` 就说明服务起来了。 + +4. 在每台电脑的 AI Agent 里填服务器地址和访问密码: + + ```json + { + "mcpServers": { + "oh-my-sage": { + "url": "http://<服务器 IP>:3790/mcp", + "headers": { "Authorization": "Bearer <访问密码>" } + } + } + } + ``` + + `Bearer` 和访问密码之间有一个空格,别删。 + +5. 每台电脑都按方式一的 [第 2 步](#2-装-skill) 装好 Skill,重启 AI Agent。然后在任意一台电脑上按 [第 4 步](#4-开始对话) 连接网关,其他电脑就不用再输登录码了。 + +云端 AI Agent(比如豆包工作)只能用这种方式,并且要让它能访问到你的服务器地址。端口、排障等细节见 [deploy/README.md](deploy/README.md#方式三私有服务器docker)。 + +#### 升级与卸载 + +| 用法 | 升级 | 卸载 | +|------|------|------| +| 按需启动 | 不用管,每次启动 AI Agent 时 `npx` 都会检查并换上最新版 | 删掉 MCP 配置里的 `oh-my-sage` | +| 本机常驻 | 重新运行 `npm install -g oh-my-sage-mcp`,再把上面第 2 步的安装脚本运行一次 | 安装脚本末尾加 `-Uninstall`(Windows)或 `-u`(macOS / Linux)运行一次,再 `npm uninstall -g oh-my-sage-mcp` | +| 私有服务器 | 在仓库目录 `git pull`,再到 `deploy` 目录运行 `docker compose up -d --build` | 在 `deploy` 目录运行 `docker compose down` | + +Skill 不会跟着 MCP Server 自动更新,升级时另外运行 `npx skills update mijia-automation -g`;卸载用 `npx skills remove mijia-automation -g`。每个版本改了什么见 [Releases](https://github.com/allocnode/oh-my-sage/releases)。 ### 方式二:网页版 -网页版自带聊天界面,但需要你自己准备一个大模型的 API Key(下面的表格里任选一家)。 +网页版自带聊天界面,但需要你自己准备一个大模型的 API Key(下面的表格里任选一家)。npm 上发布的只有 MCP Server,网页版要下载仓库运行,所以除了 Node.js 还需要装 [Git](https://git-scm.com/)。 #### 最省事:让 AI Agent 帮你装 +把下面这段话里尖括号的部分换成你自己的值,再整段发给 AI Agent。接口地址和模型名称从下文的表格里选一家: + ``` 帮我在本机部署这个项目的网页版:https://github.com/allocnode/oh-my-sage -- 大模型接口地址:https://api.deepseek.com/v1 -- API Key:(填你的 Key) -- 模型名称:deepseek-flash -- 米家中枢网关地址:http://192.168.0.5 +- 大模型接口地址: +- API Key:<你的 API Key> +- 模型名称: +- 米家中枢网关地址:http://<网关 IP> -按 README「方式二」安装依赖、写好 .env,然后启动,告诉我访问地址 +按 README「方式二」安装依赖、写好 .env,然后启动,告诉我访问地址。上面哪一项还是尖括号占位符,先问我,不要自己编 ``` #### 自己动手装 @@ -206,13 +295,17 @@ cp .env.example .env Copy-Item .env.example .env ``` -用任意文本编辑器打开 `.env`,改成你自己的值: +用任意文本编辑器打开 `.env`,把四项改成你自己的值(以 DeepSeek 为例): ```env -LLM_BASE_URL=https://api.deepseek.com/v1 # 大模型接口地址,见下表 -LLM_API_KEY=sk-xxxxxxxx # 你的 API Key -LLM_MODEL=deepseek-flash # 模型名称,见下表 -GATEWAY_URL=http://192.168.0.5 # 米家中枢网关地址,必填 +# 大模型接口地址,见下表 +LLM_BASE_URL=https://api.deepseek.com/v1 +# 你的 API Key +LLM_API_KEY=<你的 API Key> +# 模型名称,见下表 +LLM_MODEL=deepseek-flash +# 米家中枢网关地址,必填 +GATEWAY_URL=http://<网关 IP> ``` | 服务商 | `LLM_BASE_URL` | `LLM_MODEL` 示例 | @@ -233,13 +326,13 @@ GATEWAY_URL=http://192.168.0.5 # 米家中枢网关地址,必填 npm run dev ``` -看到 `Ready` 字样后,用浏览器打开 http://localhost:3000 。 +看到 `Ready` 字样后,用浏览器打开 http://localhost:3000 。`npm run dev` 是开发模式,第一次打开页面要等它编译;长期使用可以先运行一次 `npm run build`,以后用 `npm start` 启动,打开更快。 ##### 4. 登录并开始对话 在米家 App 的「自动化极客版」页面取一个新的登录码,输进网页里,输满 6 位会自动连接。连上后左边能看到你家的设备,直接在中间的输入框里提需求就行。 -网页版直接读取仓库里的 Skill,不用另外安装。对话记录保存在仓库下的 `.sessionstore/` 目录。 +网页版直接读取仓库里的 Skill,不用另外安装。对话记录保存在仓库下的 `.sessionstore/` 目录。以后更新时,先停掉网页服务,在仓库目录运行 `git pull` 和 `npm install`(用 `npm start` 的还要再 `npm run build`),再重新启动。 --- @@ -435,10 +528,16 @@ off set 客厅吸顶灯 2/1 = false 登录码只能用一次,不管成功还是失败,用过就作废了。从网关重新取一个新的。 **AI Agent 每次重启都要重新输登录码?** -这是 stdio 方式的特点,进程跟着客户端一起退出。改用「本机常驻」或「私有服务器」,网关只登录一次。 +这是按需启动方式的特点,进程跟着 AI Agent 一起退出。改用 [本机常驻](#换成本机常驻) 或 [私有服务器](#换成私有服务器docker),网关只登录一次。 + +**AI Agent 里看不到 oh-my-sage,或者显示连接失败?** +先在终端里运行 `npx -y oh-my-sage-mcp --version`。打印出版本号说明包能正常下载运行,问题在 MCP 配置,检查 JSON 格式和字段名(不同 AI Agent 的写法见 [客户端配置](deploy/README.md#客户端配置));报错的话,多半是 Node.js 版本低于 20,或者网络访问不了 npm。 + +**连不上网关?** +确认电脑和网关在同一个局域网,`GATEWAY_URL` 是 `http://` 加网关 IP,并且米家 App 里的「自动化极客版」已经开启。 **AI 说创建规则需要 Skill?** -AI Agent 没读到 `mijia-automation` Skill,按 [快速开始](#快速开始) 方式一的第 2 步装好再试。 +AI Agent 没读到 `mijia-automation` Skill,按方式一的 [第 2 步](#2-装-skill) 装好,再重启 AI Agent。 --- diff --git a/deploy/.env.example b/deploy/.env.example index 280c578..a787f79 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -1,14 +1,18 @@ # oh-my-sage MCP Server - Docker 部署配置(私有服务器 / NAS) -# 复制为 deploy/.env 后修改,不要提交 .env。 +# 复制为 deploy/.env 后填写,不要提交 .env。 +# 下面的值都是留空的,必须换成你自己的;MCP_AUTH_TOKEN 和 MCP_ALLOWED_HOSTS 留空时 docker compose 会拒绝启动。 -# 米家网关局域网地址 -GATEWAY_URL=http://192.168.0.5 +# 米家中枢网关地址,例如 http://192.168.0.5 +# 留空也能启动,但第一次连接网关时要把地址告诉 AI Agent +GATEWAY_URL= -# 客户端连接时携带的 Bearer token,生成方式:openssl rand -hex 32 -MCP_AUTH_TOKEN=change-me-to-a-long-random-string +# 访问密码:客户端连接时携带的 Bearer token,必填 +# 生成方式:openssl rand -hex 32 +MCP_AUTH_TOKEN= -# 客户端访问服务器时使用的主机名或 IP(逗号分隔),否则请求会被 Host 校验拒绝(403) -MCP_ALLOWED_HOSTS=192.168.0.10,nas.local +# 其他电脑访问这台服务器时使用的 IP 或域名,必填,多个用英文逗号隔开,不带端口 +# 例如 192.168.0.10,nas.local;漏掉的地址访问时会被 Host 校验拒绝(403) +MCP_ALLOWED_HOSTS= # 宿主机映射端口 MCP_PORT=3790 diff --git a/deploy/README.md b/deploy/README.md index 1295599..a67a98d 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -10,13 +10,15 @@ oh-my-sage 的 MCP Server 有三种部署方式,工具和功能完全相同, 后两种走 Streamable HTTP(`/mcp`):进程常驻,请求不经过 stdio 路径,因此并发工具调用较多时也不会刷 `MaxListenersExceededWarning`(该告警来自 MCP SDK stdio 客户端为每个并发请求在流上挂 `drain` 监听器,属于日志噪音,不影响工具执行结果)。无论用哪种方式,客户端都不需要额外处理这个告警。 -改完部署方式后,客户端配置见下文 [客户端配置](#客户端配置)。 +改完部署方式后,客户端配置见下文 [客户端配置](#客户端配置)。下文命令和配置里的 `<网关 IP>`、`<服务器 IP>`、`<访问密码>` 都是占位符,换成你自己的值,尖括号不要保留。 --- ## 方式一:stdio -由客户端按需拉起进程,无需部署脚本。客户端配置见 [主 README](../README.md#方式一mcp)。 +由客户端按需拉起进程,无需部署脚本。客户端配置见下文 [客户端配置](#客户端配置),分步说明见 [主 README](../README.md#方式一在-ai-agent-里用mcp)。 + +`npx -y oh-my-sage-mcp` 不带版本号时,每次启动都会向 npm 查询最新版,有新版本就自动换上,不需要手动升级。想固定版本,写成 `oh-my-sage-mcp@<版本号>`,可用版本见 [npm](https://www.npmjs.com/package/oh-my-sage-mcp?activeTab=versions)。 --- @@ -28,12 +30,14 @@ oh-my-sage 的 MCP Server 有三种部署方式,工具和功能完全相同, npm install -g oh-my-sage-mcp ``` -下面命令里的 `$(npm root -g)/oh-my-sage-mcp` 是全局安装目录。从仓库源码安装时,先在仓库根目录执行 `npm run build:mcp`,再把路径换成仓库里的 `deploy/` 即可。升级时重新 `npm install -g oh-my-sage-mcp`,再运行一次安装脚本。 +下面命令里的 `$(npm root -g)/oh-my-sage-mcp` 是全局安装目录。服务直接运行这个目录里的代码,升级时重新 `npm install -g oh-my-sage-mcp`,再运行一次安装脚本让服务重启。 + +从仓库源码安装(开发用):在仓库根目录执行 `npm run build:mcp`,再把命令里的路径换成仓库里的 `deploy/`。 ### macOS / Linux ```bash -bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -g http://192.168.0.5 +bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -g "http://<网关 IP>" ``` | 参数 | 说明 | @@ -50,9 +54,11 @@ bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -g http://192.168.0 ### Windows ```powershell -pwsh "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl http://192.168.0.5 +powershell -ExecutionPolicy Bypass -File "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl "http://<网关 IP>" ``` +在 PowerShell 里运行。`-ExecutionPolicy Bypass` 只对这一次运行生效,用来绕过 Windows 默认禁止运行脚本的设置,不会改系统配置。装了 PowerShell 7 的也可以把 `powershell` 换成 `pwsh`。 + | 参数 | 说明 | |------|------| | `-GatewayUrl` | 网关地址,默认取 `$env:GATEWAY_URL` | @@ -70,17 +76,22 @@ pwsh "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl http:/ ## 方式三:私有服务器(Docker) ```bash -cp deploy/.env.example deploy/.env # 填入 GATEWAY_URL、MCP_AUTH_TOKEN、MCP_ALLOWED_HOSTS -cd deploy && docker compose up -d --build +git clone https://github.com/allocnode/oh-my-sage.git +cd oh-my-sage/deploy +cp .env.example .env # 填入 GATEWAY_URL、MCP_AUTH_TOKEN、MCP_ALLOWED_HOSTS +docker compose up -d --build +curl -s http://<服务器 IP>:3790/healthz # {"ok":true,...} 即启动成功 ``` +镜像在服务器本地从源码构建。升级:在仓库目录 `git pull`,再到 `deploy` 目录重新 `docker compose up -d --build`。 + `deploy/.env` 需要设置: | 变量 | 说明 | |------|------| | `GATEWAY_URL` | 米家网关局域网地址 | | `MCP_AUTH_TOKEN` | 客户端携带的 Bearer token,`openssl rand -hex 32` 生成;**未设置会拒绝启动** | -| `MCP_ALLOWED_HOSTS` | 客户端访问服务器时用的主机名或 IP,逗号分隔;缺失会导致 Host 校验返回 403 | +| `MCP_ALLOWED_HOSTS` | 客户端访问服务器时用的主机名或 IP,逗号分隔,不带端口;缺失会导致 Host 校验返回 403 | | `MCP_PORT` | 宿主机映射端口,默认 `3790` | 镜像为多阶段构建,运行阶段只装 MCP 实际引用的依赖(约 14 MB,不含 Next.js / antd 等 Web 端依赖)。`deploy/mcp-runtime-package.mjs` 扫描编译产物生成这份最小依赖清单。 @@ -101,7 +112,7 @@ cd deploy && docker compose up -d --build "oh-my-sage": { "command": "npx", "args": ["-y", "oh-my-sage-mcp"], - "env": { "GATEWAY_URL": "http://192.168.0.5" } + "env": { "GATEWAY_URL": "http://<网关 IP>" } } } } @@ -115,7 +126,7 @@ cd deploy && docker compose up -d --build "oh-my-sage": { "type": "local", "command": ["npx", "-y", "oh-my-sage-mcp"], - "environment": { "GATEWAY_URL": "http://192.168.0.5" } + "environment": { "GATEWAY_URL": "http://<网关 IP>" } } } } @@ -127,22 +138,37 @@ cd deploy && docker compose up -d --build ### HTTP(Streamable HTTP 客户端) -把地址换成实际部署地址,端口默认 `3790`: +本机常驻用 `http://127.0.0.1:3790/mcp`,私有服务器用 `http://<服务器 IP>:3790/mcp`: ```json { "mcpServers": { "oh-my-sage": { - "url": "http://127.0.0.1:3790/mcp", - "headers": { "Authorization": "Bearer " } + "url": "http://<服务器 IP>:3790/mcp", + "headers": { "Authorization": "Bearer <访问密码>" } } } } ``` -若客户端的 HTTP 配置字段名不同(如 `serverUrl`、`transport` 等),按该客户端文档对应填写;需要鉴权时把 token 放进 `headers`,未设置 token 时去掉 `headers`。 +若客户端的 HTTP 配置字段名不同(如 `serverUrl`、`transport` 等),按该客户端文档对应填写;需要鉴权时把 token 放进 `headers`,未设置 token 时(本机常驻默认不设)去掉 `headers`。 + +OpenCode 的写法: + +```json +{ + "mcp": { + "oh-my-sage": { + "type": "remote", + "url": "http://<服务器 IP>:3790/mcp", + "oauth": false, + "headers": { "Authorization": "Bearer <访问密码>" } + } + } +} +``` -部署在私有服务器时把地址换成服务器的主机名或 IP(并列入 `MCP_ALLOWED_HOSTS`)。 +部署在私有服务器时,地址里用的主机名或 IP 必须列入 `MCP_ALLOWED_HOSTS`。 --- @@ -188,7 +214,7 @@ curl -s http://127.0.0.1:3790/healthz **服务未启动** -安装脚本会打印日志位置。macOS:`~/Library/Logs/oh-my-sage-mcp.log`;Linux:`journalctl --user -u oh-my-sage-mcp`;Windows:查看计划任务「oh-my-sage-mcp」的运行结果。 +安装脚本健康检查失败时会提示排查方法。macOS:`~/Library/Logs/oh-my-sage-mcp.log`;Linux:`journalctl --user -u oh-my-sage-mcp`;Windows:在「任务计划程序」里查看任务「oh-my-sage-mcp」的上次运行结果,或按脚本提示的命令在前台运行一次看报错;Docker:`docker compose logs oh-my-sage-mcp`。 **端口被占用** diff --git a/deploy/install-local.ps1 b/deploy/install-local.ps1 index b09ce0e..809a398 100644 --- a/deploy/install-local.ps1 +++ b/deploy/install-local.ps1 @@ -1,4 +1,4 @@ -<# +<# .SYNOPSIS 将 oh-my-sage MCP Server 安装为本机常驻服务(Windows,HTTP 模式,仅监听 127.0.0.1)。 @@ -12,12 +12,12 @@ .EXAMPLE npm install -g oh-my-sage-mcp - pwsh "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl http://192.168.0.5 + powershell -ExecutionPolicy Bypass -File "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.ps1" -GatewayUrl "http://<网关 IP>" .EXAMPLE npm run build:mcp - pwsh deploy/install-local.ps1 -GatewayUrl http://192.168.0.5 - pwsh deploy/install-local.ps1 -GatewayUrl http://192.168.0.5 -Port 3791 -Token (openssl rand -hex 32) - pwsh deploy/install-local.ps1 -Uninstall + powershell -ExecutionPolicy Bypass -File deploy/install-local.ps1 -GatewayUrl "http://<网关 IP>" + powershell -ExecutionPolicy Bypass -File deploy/install-local.ps1 -GatewayUrl "http://<网关 IP>" -Port 3791 -Token "<访问密码>" + powershell -ExecutionPolicy Bypass -File deploy/install-local.ps1 -Uninstall #> [CmdletBinding()] param( diff --git a/deploy/install-local.sh b/deploy/install-local.sh index 6080b8f..635a20a 100644 --- a/deploy/install-local.sh +++ b/deploy/install-local.sh @@ -4,8 +4,8 @@ # Linux: systemd --user 服务(Restart=on-failure) # # 用法(npm install -g oh-my-sage-mcp 后运行包里的这个脚本,或在仓库根目录先 npm run build:mcp): -# bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" [-g 网关地址] [-p 端口] [-t token] [-n 服务名] -# deploy/install-local.sh -u # 卸载 +# bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" [-g http://<网关 IP>] [-p 端口] [-t 访问密码] [-n 服务名] +# bash "$(npm root -g)/oh-my-sage-mcp/deploy/install-local.sh" -u # 卸载 set -euo pipefail GATEWAY_URL="${GATEWAY_URL:-}" diff --git a/docs/images/install.webp b/docs/images/install.webp index a1b297d..49c5617 100644 Binary files a/docs/images/install.webp and b/docs/images/install.webp differ