From 89f984a337f23583a91a2b279769954aa0a2f583 Mon Sep 17 00:00:00 2001
From: Jax <jax@luzcorp.com>
Date: Fri, 13 Mar 2026 18:37:42 +0800
Subject: [PATCH] docs: clarify development and published stdio usage

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---
 README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 889cd74..0465629 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Stdio 是本模板在本地开发以及与 Claude 等桌面 LLM 客户端集成
    ```
 
 2. **使用 MCP Inspector 运行**
-   模板在 `package.json` 中提供了协议安全的启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：
+   模板在 `package.json` 中提供了一个仅用于工作区开发的协议安全 `mcp.stdio` 启动配置，用于避免 stdout 被污染。你可以使用以下命令测试服务端：
    ```bash
    pnpm dlx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
    ```
@@ -35,6 +35,57 @@ Stdio 是本模板在本地开发以及与 Claude 等桌面 LLM 客户端集成
    pnpm build
    ```
 
+4. **已发布包使用 `npx` 启动**
+   如果你把这个模板产物发布到了 npm，并且保留了默认的 `bin` 映射，使用者可以直接通过包名启动 stdio 服务：
+   ```bash
+   npx -y <your-package-name>
+   ```
+   构建后，发布产物会直接提供扁平的 `dist/stdio.js` 入口，并作为 npm `bin` 暴露出来，适合分发后的 MCP client 集成场景。
+
+### OpenCode 配置示例
+
+如果你想在 OpenCode 中把这个模板作为本地 MCP server 挂进去，可以在项目级 `opencode.jsonc` 里加入一段本地 MCP 配置。下面这个示例和当前 `package.json` 中仅用于开发态的 `mcp.stdio` 启动参数保持一致：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "template_stdio": {
+      "type": "local",
+      "enabled": true,
+      "command": [
+        "node",
+        "./node_modules/tsx/dist/cli.mjs",
+        "src/stdio.ts"
+      ]
+    }
+  }
+}
+```
+
+如果你把配置放在全局 OpenCode 配置里，需要把 `command` 里的相对路径改成这个项目的绝对路径，或者把 OpenCode 的工作目录指向仓库根目录。这样可以避免找不到 `./node_modules/tsx/dist/cli.mjs` 或 `src/stdio.ts`。
+
+如果你是通过 npm 发布后的包来接入 OpenCode，也可以改成直接走 `npx` 的分发态启动方式：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "template_stdio": {
+      "type": "local",
+      "enabled": true,
+      "command": ["npx", "-y", "<your-package-name>"]
+    }
+  }
+}
+```
+
+这种方式更适合已经发布的包；而模板开发阶段，仍然建议优先使用上面的源码启动配置。
+
+## 发布面验证
+
+- **发布入口检查**：`pnpm test:publish`（打包本地 tarball，并通过包的 `bin` 名启动一次 stdio 服务）
+
 ## 使用方式：HTTP
 
 HTTP 传输基于 Node 原生的 `StreamableHTTPServerTransport`，适用于远程连接或基于 Web 的接入场景。