toolhome 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ToolHome contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# ToolHome
+
+> **🌐 Language: English · [中文](README.zh.md)**
+
+ToolHome is a single-user, self-hosted control plane for MCP servers and Hosted CLIs. Manage upstream MCP capabilities, platform CLIs such as Azure `az`, GitHub `gh`, and Tailscale, and their encrypted credentials in one place.
+
+It exposes two data planes:
+
+- **MCP**: `POST /mcp` aggregates enabled servers; `POST /mcp/{server_slug}` preserves one server's original names and extensions.
+- **Hosted CLI**: `POST /cli/{slug}/exec` runs an allow-listed argv array on the ToolHome host or in a pinned sibling container and streams NDJSON stdout/stderr/exit frames. `GET /cli/{slug}/status` runs the declared status probe.
+
+ToolHome does not write harness-specific adapters for Claude Code, Codex, Cursor, or anything else. MCP clients use standard Streamable HTTP with Bearer auth; management and Hosted CLI operations use Control Keys.
+
+## For AI Agents
+
+Install the ToolHome skill to teach your agent how to deploy and manage ToolHome:
+
+```bash
+npx skills add crayonlu/toolhome -g -y
+```
+
+This gives the agent knowledge of all CLI commands, OAuth flows, Market installation, troubleshooting, and deployment patterns. The agent will know when and how to use ToolHome without manual instructions.
+
+## Web Console
+
+The web console mirrors the full CLI surface: server and credential management, OAuth authorization, one-click Market installs, tool call observability, diagnostics, events, config export/import — with Chinese/English UI and mobile support.
+
+<div style="display: flex; flex-wrap: wrap; gap: 8px;">
+  <img src="docs/screenshots/en/dashboard.png" width="49%" alt="Dashboard">
+  <img src="docs/screenshots/en/servers.png" width="49%" alt="Servers">
+  <img src="docs/screenshots/en/calls.png" width="49%" alt="Calls">
+  <img src="docs/screenshots/en/credentials.png" width="49%" alt="Credentials">
+  <img src="docs/screenshots/en/market.png" width="49%" alt="Market">
+  <img src="docs/screenshots/en/settings.png" width="49%" alt="Settings">
+</div>
+
+Mobile:
+
+<div style="display: flex; gap: 8px;">
+  <img src="docs/screenshots/en/market-mobile.png" width="49%" alt="Market mobile">
+  <img src="docs/screenshots/en/dashboard-mobile.png" width="49%" alt="Dashboard mobile">
+</div>
+
+## Project Scope
+
+ToolHome has two first-class planes:
+
+- **MCP**: Remote-native servers use Streamable HTTP; Home-hosted servers use stdio on the ToolHome host.
+- **Hosted CLI**: platform CLIs represent an external service or control plane, for example Azure `az`, GitHub `gh`, and Tailscale. They are invoked with complete argv, stdin, timeout and output limits, allow/deny rules, and NDJSON output frames. Package managers and developer tools such as `npm`, `go`, `cargo`, `uv`, `pipx`, `docker`, and `cursor` are installer/runtime details, not Hosted CLI products.
+
+MCPs or CLIs that must run on the harness machine and depend on its browser or desktop state remain local to that harness. The first release explicitly excludes multi-tenancy, profiles, workspaces, and project management.
+
+## Protocol Capabilities
+
+The per-server entry proxies losslessly; the aggregate virtualizes conflicting names while keeping everything routable:
+
+- Tools, Prompts, Resources, Resource Templates, Completion
+- Resource subscriptions and list-changed notifications
+- Sampling, Roots, Elicitation, and 2026 MRTR `input_required`
+- Final Tasks extension: `tasks/get`, `tasks/update`, `tasks/cancel`, task-ID virtualization, and `Mcp-Name` binding
+- MCP Apps: `ui://` URIs are preserved on the aggregate; original App semantics on per-server entries
+- Logging, Progress, cancellation, and custom extension methods
+- Automatic 2026-07-28 / 2025-era negotiation, with remote SSE available as an explicit fallback
+
+Downstream 2026 requests stay stateless; 2025-era clients use a persistent session bound to the authenticated principal, preserving initialize capability declarations and bidirectional request semantics. Parts of the Final Tasks extension not yet registered by SDK 2.0 are filled in by an isolated compatibility layer that still speaks the official `tasks/*` wire contract.
+
+Aggregated tool names are `{server_slug}.{upstream_name}`. Unknown extension methods use `toolhome/{server_slug}/{upstream_method}` on the aggregate and pass through untouched on per-server entries. MCP Apps that use original tool names are routed by App resource context or globally unique names; use a per-server entry when names collide.
+
+When a modern harness calls a legacy upstream, ToolHome suspends push-style Elicitation, Sampling, and Roots in Tool, Prompt, and Resource Read calls, converts them to modern `input_required` multi-turn interactions, then resumes the same upstream request. Legacy extensions that issue private server-to-client requests inside a custom method have no standard representation in the closed MRTR type set; use a legacy harness or upgrade the upstream protocol for those.
+
+See [architecture](docs/architecture.md) and [protocol compatibility](docs/protocol-compatibility.md) for details.
+
+## Quick Start
+
+Requires Node.js 24 or newer.
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Generate two independent random values for `TOOLHOME_MASTER_KEY` and the first-boot `TOOLHOME_BOOTSTRAP_CONTROL_KEY`. Both must be at least 32 characters and must differ.
+
+```bash
+npm run build
+set -a
+source .env
+set +a
+npm start
+```
+
+Open `TOOLHOME_PUBLIC_URL` and sign in to the web console with the bootstrap Control API Key. Once you create a new Control Key, you can revoke the bootstrap key.
+
+For development, run the server and web separately:
+
+```bash
+npm run dev
+npm run dev:web
+```
+
+Vite proxies `/api` requests to `http://127.0.0.1:3344`.
+
+## Docker
+
+```bash
+export TOOLHOME_MASTER_KEY="$(openssl rand -base64 48)"
+export TOOLHOME_BOOTSTRAP_CONTROL_KEY="tch_ctl_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
+export TOOLHOME_PUBLIC_URL="https://tool.cyncyn.xyz"
+export TOOLHOME_ALLOWED_HOSTS="tool.cyncyn.xyz"
+docker compose up -d --build
+```
+
+Put an HTTPS reverse proxy in front of ToolHome in production. OAuth callbacks, URL-based Client IDs, and remote harness connections should all use a stable HTTPS `TOOLHOME_PUBLIC_URL`. The value must be a canonical origin — no path, query, fragment, username, or password. Data lives in `/data/toolhome.sqlite` (SQLite, WAL mode).
+
+Market installers are hidden behind curated capability entries. The catalog can use npm, Go, GitHub Release archives, uvx, or Docker recipes; the product surface remains MCP servers and Hosted platform CLIs. Uvx entries execute the installed binary from the persistent ToolHome tool directory instead of resolving the package again on every refresh. Docker-backed entries require the Docker socket mount shown in `docker-compose.yml`. Hosted CLI state directories are explicit named volumes, never implicit mounts of a user's local credential directory.
+
+## CI/CD
+
+GitHub Actions (`.github/workflows/ci.yml`) runs on every push to main or tag:
+
+1. **test**: server check + test, web typecheck + test
+2. **docker**: build dists -> `docker build` -> push `ghcr.io/crayonlu/toolhome:latest` (tags also get `:v*`)
+3. **deploy**: SSH to server `docker compose pull && up -d`
+
+Deployment requires three GitHub Secrets: `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_KEY` (SSH private key). The GHCR package must be set to Public (after first push, in Package Settings).
+
+## Market
+
+The Market ships curated MCP servers and Hosted platform CLIs. Installing an entry creates the encrypted Credential and the corresponding Server or CLI record:
+
+```bash
+npm run cli -- market list
+npm run cli -- market install resend --set RESEND_API_KEY=re_xxx
+npm run cli -- market install gh-cli --set GH_TOKEN=ghp_xxx
+npm run cli -- market uninstall gh-cli
+```
+
+- MCP entries may be remote, npm-backed, uvx-backed, or Docker-backed.
+- Hosted CLI entries include Azure `az`, GitHub `gh`, and Tailscale. They pin the platform artifact, define allowed argv, and declare how stored credential material reaches the CLI.
+- A CLI can use a bearer token (`GH_TOKEN`), selected Env Credential variables (Azure service principal), or an OAuth access token after the shared MCP authorization flow completes.
+- The web console's Market page offers the same flow graphically. MCP/CLI is a plane switch: only entries and records from the selected plane are shown.
+
+## Connecting a Harness
+
+First create an MCP Access API Key from the console or CLI. The generic aggregate configuration is:
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp",
+  "headers": {
+    "Authorization": "Bearer tch_mcp_..."
+  }
+}
+```
+
+For a single GitHub server only:
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp/github",
+  "headers": {
+    "Authorization": "Bearer tch_mcp_..."
+  }
+}
+```
+
+Access Keys only call the MCP data plane; they cannot read server or credential configuration. Control Keys only call the control plane and cannot be used as an MCP identity.
+
+The data plane also implements OAuth 2.1: a harness can discover the authorization server via RFC 9728 metadata and use Authorization Code + PKCE to obtain an access token bound to a specific MCP endpoint.
+
+Downstream Dynamic Client Registration returns a stateless Client ID signed with the master key — no in-process registry, valid across restarts with the same key. HTTPS URL-based Client Metadata is also supported, with limits on response size, redirects, and non-public targets.
+
+## Upstream Authentication
+
+Remote-native servers support:
+
+- Bearer token
+- API key header
+- Multiple custom headers
+- OAuth 2.1 / OIDC
+
+OAuth/OIDC uses the official MCP TypeScript SDK auth orchestrator, covering RFC 9728 discovery, Authorization Server/OIDC metadata, PKCE, RFC 9207 issuer validation, CIMD, DCR, refresh, and RFC 8707 resource indicators. An OAuth Credential is bound 1:1 to a Remote Server, preventing token reuse across resources or issuers.
+
+> If an upstream authorization server advertises URL-based Client Metadata support but cannot fetch it from a proxied origin (for example Cloudflare-hosted MCP), set `TOOLHOME_OAUTH_URL_CLIENT_ID=false` to force Dynamic Client Registration.
+
+Home-hosted servers use an Environment Credential or the transport's own `env`.
+
+Put secrets in Credentials, not in Remote URL query strings or stdio arguments — the latter are structural configuration and cannot be reliably redacted.
+
+## CLI
+
+After building, run `toolhome`; from source, use `npm run cli --`.
+
+```bash
+export TOOLHOME_URL="https://tool.cyncyn.xyz"
+export TOOLHOME_CONTROL_KEY="tch_ctl_<your-control-key>"
+# Optional: override the default ~/.config/toolhome/config.json path
+export TOOLHOME_CONFIG="$HOME/.config/toolhome/config.json"
+npm run cli -- auth login
+
+npm run cli -- server list
+npm run cli -- server add ./server.json
+npm run cli -- cli list
+npm run cli -- cli status az
+npm run cli -- cli exec az -- account show
+npm run cli -- cli exec gh --stdin-file ./input.txt -- issue list
+npm run cli -- credential authorize cloudflare
+npm run cli -- access-key create laptop
+npm run cli -- endpoint aggregate
+npm run cli -- doctor
+```
+
+`cli exec` sends an argv array to the hosted CLI and streams stdout/stderr without invoking a shell. Put `--` before CLI arguments that start with `-`; `--stdin` and `--stdin-file` feed remote stdin, and `--output json` emits one JSON object per frame plus the final exit outcome:
+
+```bash
+npm run cli -- cli exec az --timeout 30000 -- account show --subscription "$SUBSCRIPTION_ID"
+npm run cli -- cli exec gh --stdin-file ./issue.md -- issue create --title "Bug" --body-file -
+npm run cli --output json -- cli exec host-shell -- -c 'printf hello'
+```
+
+The CLI command family also supports `cli get`, `cli add`, `cli update`, `cli delete`, `cli enable`, and `cli disable`. `cli exec` returns exit status 0 only when the hosted process reports `result: "ok"`; SIGINT/SIGTERM abort the HTTP stream and the remote process.
+
+`credential authorize <name>` resolves by credential name (or id), opens the browser, and waits until authorization succeeds, fails, or times out:
+
+```bash
+npm run cli -- credential authorize notion --server notion   # explicit server (auto-resolved if omitted)
+npm run cli -- credential authorize notion --force            # clear the old client and re-authorize
+npm run cli -- credential authorize notion --no-open          # don't open the browser
+npm run cli -- credential authorize notion --no-wait          # print the URL and exit
+npm run cli -- credential authorize notion --timeout 300      # wait time in seconds (default 600)
+```
+
+The CLI exposes a command for every Control API capability plus a general escape hatch:
+
+```bash
+npm run cli -- api GET /api/v1/openapi.json
+```
+
+Config export is redacted and reviewable by default, and cannot be used to restore. Credential payloads, static HTTP header values, and stdio transport env values are hidden. When secrets are explicitly included, the CLI writes the file with `0600` permissions; import rebuilds credentials, remaps related IDs, and rolls back atomically in a single SQLite transaction if any step fails.
+
+```bash
+npm run cli -- config export backup.json --include-secrets
+npm run cli -- config import backup.json
+```
+
+Backups contain plaintext secrets and deserve the same protection as the master key. `--include-secrets` requires an explicit output file to avoid leaking secrets into terminal logs, and the CLI forces `0600` after writing. Omit it for routine review.
+
+## Configuration
+
+| Environment variable             | Description                                                                   | Default                 |
+| -------------------------------- | ----------------------------------------------------------------------------- | ----------------------- |
+| `TOOLHOME_HOST`                  | Listen address                                                                | `127.0.0.1`             |
+| `TOOLHOME_PORT`                  | Listen port                                                                   | `3344`                  |
+| `TOOLHOME_PUBLIC_URL`            | Externally reachable canonical origin (production: `https://tool.cyncyn.xyz`) | `http://127.0.0.1:3344` |
+| `TOOLHOME_DATA_DIR`              | SQLite and runtime data directory                                             | `./data`                |
+| `TOOLHOME_MASTER_KEY`            | Root key for secret encryption/signing/digests                                | required                |
+| `TOOLHOME_BOOTSTRAP_CONTROL_KEY` | Control Key written on first database boot                                    | required on first boot  |
+| `TOOLHOME_ALLOWED_HOSTS`         | Allowed Hosts, comma-separated                                                | Public URL hostname     |
+| `TOOLHOME_LOG_LEVEL`             | `debug`, `info`, `warn`, `error`                                              | `info`                  |
+| `TOOLHOME_WEB_DIR`               | Web console static files directory                                            | disabled                |
+| `TOOLHOME_MARKET_DIR`            | Market npm install directory                                                  | `<dataDir>/market`      |
+| `TOOLHOME_OAUTH_URL_CLIENT_ID`   | Enable URL-based Client Metadata                                              | `true`                  |
+
+## Security Model
+
+- Upstream secrets are AES-256-GCM encrypted before being written to SQLite.
+- The database stores an encrypted master-key check; booting with the wrong master key fails immediately instead of silently locking existing API keys.
+- API Keys are stored only as HMAC digests; the full secret is returned once at creation.
+- Control and MCP Access Keys use distinct prefixes and validation domains.
+- The web console exchanges the Control Key for a short-lived, HttpOnly, SameSite=Strict session cookie.
+- Downstream OAuth tokens have exact endpoint audiences; an aggregate token cannot call per-server endpoints and vice versa.
+- OAuth callbacks validate state, PKCE, issuer, and discovery state.
+- URL-based client metadata rejects private-network and insecure targets and pins validated public-resolved addresses for HTTPS fetches, reducing SSRF and DNS-rebinding risk.
+- Downstream DCR Client IDs are signed with the master key, verifiable across restarts, and never stored in the database.
+- Diagnostic events keep the last ~10,000 entries; Home-hosted stderr is redacted against transport env and Environment Credential values before entering the event stream.
+
+Back up the database and `TOOLHOME_MASTER_KEY`, or keep a tightly protected `--include-secrets` config export. Losing the master key makes encrypted credentials in the original database unrecoverable.
+
+## Engineering Commands
+
+```bash
+npm run check
+npm run format:check
+npm run build
+npm run test
+npm run test:real
+```
+
+`npm run test:real` prefers to launch the built ToolHome process and connects Home-hosted stdio and Remote-native HTTP fixtures. It uses the official MCP Client to verify aggregate/per-server entries, modern/legacy harnesses, Progress, cancellation, list-changed, MRTR, Tasks, and auth boundaries; it falls back to source entry points when no build artifact exists, which is handy for local debugging.
+
+`/healthz` reports process liveness only; `/readyz` returns `503` while runtime state is unavailable.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,281 @@
+# ToolHome
+
+> **🌐 中文 · [English](README.md)**
+
+ToolHome 是一个单用户、可自托管的 MCP 与 Hosted CLI 控制面。你可以在一个地方管理上游 MCP 能力、Azure `az`、GitHub `gh`、Tailscale 等平台 CLI，以及加密保存的凭据。
+
+它同时暴露两种数据面：
+
+- **MCP**：`POST /mcp` 聚合启用的 Server；`POST /mcp/{server_slug}` 保留单个 Server 的原始名称和扩展语义。
+- **Hosted CLI**：`POST /cli/{slug}/exec` 在 ToolHome 宿主机或固定版本的 sibling 容器中执行受 allow-list 限制的 argv，并以 NDJSON 流返回 stdout/stderr/exit；`GET /cli/{slug}/status` 执行声明的状态探针。
+
+ToolHome 不为 Claude Code、Codex、Cursor 或其他 Harness 编写专属适配层。MCP 客户端使用标准 Streamable HTTP 与 Bearer 鉴权；管理面和 Hosted CLI 使用 Control Key。
+
+## AI Agent 快速开始
+
+安装 ToolHome skill，让 AI agent 自动掌握 ToolHome 的部署和操作：
+
+```bash
+npx skills add crayonlu/toolhome -g -y
+```
+
+安装后 agent 会获得全部 CLI 命令、OAuth 授权流程、Market 安装、排错和部署模式的知识，无需手动编写指令。
+
+## Web 控制台
+
+控制台提供与 CLI 完全对齐的功能：服务器与凭据管理、OAuth 授权、Market 一键安装、调用观测、诊断、事件、配置导入导出，以及中英双语和移动端适配。
+
+<div style="display: flex; flex-wrap: wrap; gap: 8px;">
+  <img src="docs/screenshots/zh/dashboard.png" width="49%" alt="Dashboard">
+  <img src="docs/screenshots/zh/servers.png" width="49%" alt="Servers">
+  <img src="docs/screenshots/zh/calls.png" width="49%" alt="Calls">
+  <img src="docs/screenshots/zh/credentials.png" width="49%" alt="Credentials">
+  <img src="docs/screenshots/zh/market.png" width="49%" alt="Market">
+  <img src="docs/screenshots/zh/settings.png" width="49%" alt="Settings">
+</div>
+
+移动端：
+
+<div style="display: flex; gap: 8px;">
+  <img src="docs/screenshots/zh/market-mobile.png" width="49%" alt="Market mobile">
+  <img src="docs/screenshots/zh/dashboard-mobile.png" width="49%" alt="Dashboard mobile">
+</div>
+
+## 项目边界
+
+ToolHome 有两个一等平面：
+
+- **MCP**：Remote-native 使用 Streamable HTTP；Home-hosted 使用 ToolHome 宿主机上的 stdio。
+- **Hosted CLI**：CLI 必须代表外部平台或 SaaS 控制面，例如 Azure `az`、GitHub `gh`、Tailscale。它支持完整 argv、stdin、timeout、输出限制、allow/deny 规则和 NDJSON 输出。`npm`、`go`、`cargo`、`uv`、`pipx`、`docker`、`cursor` 等安装器或开发工具只是实现细节，不是 Hosted CLI 产品。
+
+必须运行在 Harness 所在本机、依赖该机器浏览器或桌面状态的 MCP/CLI 仍属于 Harness 本地配置。首版明确不包含多租户、Profile、Workspace 或 Project 管理。
+
+## 协议能力
+
+独立入口以无损代理为目标，聚合入口在保持可路由性的前提下虚拟化冲突名称：
+
+- Tools、Prompts、Resources、Resource Templates、Completion
+- Resource subscriptions 与 list-changed 通知
+- Sampling、Roots、Elicitation 与 2026 MRTR `input_required`
+- 最终 Tasks 扩展：`tasks/get`、`tasks/update`、`tasks/cancel`、任务 ID 虚拟化和 `Mcp-Name` 绑定
+- MCP Apps，聚合入口保留 `ui://` URI；独立入口保持原始 App 语义
+- Logging、Progress、取消与自定义扩展方法
+- 2026-07-28 与 2025-era 自动协商，远程 SSE 可显式作为回退
+
+下游 2026 请求保持无状态；2025-era 使用与认证 principal 绑定的持久 Session，保留 initialize 能力声明和双向请求语义。最终 Tasks extension 在 SDK 2.0 尚未注册的部分由隔离兼容层补齐，对外仍是官方 `tasks/*` wire contract。
+
+聚合工具名为 `{server_slug}.{upstream_name}`。未知扩展方法在聚合入口使用 `toolhome/{server_slug}/{upstream_method}`；独立入口原样透传。MCP App 若使用原始工具名，ToolHome 会根据 App 资源上下文或全局唯一名称路由；存在同名歧义时应使用独立入口。
+
+当现代 Harness 调用旧式上游时，ToolHome 会把 Tool、Prompt 和 Resource Read 中的 push-style Elicitation、Sampling、Roots 暂停并转换成现代 `input_required` 多轮交互，再恢复同一个上游请求。旧式自定义扩展若在自定义 method 内主动发起私有 server-to-client request，则没有可映射到现代 MRTR 封闭类型集的标准表示；这类扩展应使用 legacy Harness 或升级上游协议。
+
+更多细节见 [架构说明](docs/architecture.md) 和 [协议兼容说明](docs/protocol-compatibility.md)。
+
+## 快速开始
+
+需要 Node.js 24 或更新版本。
+
+```bash
+npm install
+cp .env.example .env
+```
+
+生成两个独立随机值，分别填写 `TOOLHOME_MASTER_KEY` 和首次启动所需的 `TOOLHOME_BOOTSTRAP_CONTROL_KEY`。二者都至少 32 个字符，且不能相同。
+
+```bash
+npm run build
+set -a
+source .env
+set +a
+npm start
+```
+
+打开 `TOOLHOME_PUBLIC_URL`，使用 bootstrap Control API Key 登录 Web 控制台。创建新的 Control Key 后，可以撤销 bootstrap key。
+
+开发模式分别运行：
+
+```bash
+npm run dev
+npm run dev:web
+```
+
+Vite 会把 `/api` 请求代理到 `http://127.0.0.1:3344`。
+
+## Docker
+
+```bash
+export TOOLHOME_MASTER_KEY="$(openssl rand -base64 48)"
+export TOOLHOME_BOOTSTRAP_CONTROL_KEY="tch_ctl_$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')"
+export TOOLHOME_PUBLIC_URL="https://tool.cyncyn.xyz"
+export TOOLHOME_ALLOWED_HOSTS="tool.cyncyn.xyz"
+docker compose up -d --build
+```
+
+生产环境应在 ToolHome 前放置 HTTPS 反向代理。OAuth 回调、URL-based Client ID 和远程 Harness 接入都应使用稳定的 HTTPS `TOOLHOME_PUBLIC_URL`。该值必须是规范 origin，不能包含路径、查询、fragment 或用户名密码。数据保存在 `/data/toolhome.sqlite`，SQLite 使用 WAL 模式。
+
+Market 安装器隐藏在 curated 能力条目之后，可以使用 npm、Go、GitHub Release archive、uvx 或 Docker recipe；产品表面仍然只有 MCP Server 和 Hosted 平台 CLI。Uvx 条目直接执行持久化 ToolHome 工具目录中的已安装二进制，不会在每次刷新时重新解析包。Docker 条目需要 `docker-compose.yml` 中的 Docker socket 挂载。Hosted CLI 的状态目录由条目显式声明为 Docker named volume，ToolHome 不会默认挂载用户本机的认证目录。
+
+## CI/CD
+
+GitHub Actions（`.github/workflows/ci.yml`）在 push 到 main 或打 tag 时自动执行：
+
+1. **test**：服务端 check + test，前端 typecheck + test
+2. **docker**：构建 dist -> `docker build` -> 推送 `ghcr.io/crayonlu/toolhome:latest`（tag 额外打 `:v*` 版本标签）
+3. **deploy**：SSH 到服务器 `docker compose pull && up -d`
+
+部署需要三个 GitHub Secret：`DEPLOY_HOST`、`DEPLOY_USER`、`DEPLOY_KEY`（SSH 私钥）。GHCR 镜像包需设为 Public（首次推送后在 Package Settings 里改）。
+
+## Market
+
+Market 提供 curated 的 MCP Server 和 Hosted 平台 CLI。一键安装会创建加密 Credential，以及对应的 Server 或 CLI record：
+
+```bash
+npm run cli -- market list
+npm run cli -- market install resend --set RESEND_API_KEY=re_xxx
+npm run cli -- market install gh-cli --set GH_TOKEN=ghp_xxx
+npm run cli -- market uninstall gh-cli
+```
+
+- MCP 条目可以是 remote、npm、uvx 或 Docker 实现。
+- Hosted CLI 条目包含 Azure `az`、GitHub `gh`、Tailscale；它们固定平台 artifact 版本，声明 argv allow-list，并声明如何把已保存凭据映射给 CLI。
+- CLI 可以使用 bearer token（`GH_TOKEN`）、Env Credential 中选定的变量（Azure service principal），或共享 MCP OAuth 授权流程完成后的 access token。
+- Web 控制台的 Market 页提供相同流程；MCP/CLI 是平面 switch，切换后只显示当前平面的条目和记录。
+
+## Harness 接入
+
+先在控制台或 CLI 创建 MCP Access API Key。聚合入口的通用配置等价于：
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp",
+  "headers": {
+    "Authorization": "Bearer tch_mcp_..."
+  }
+}
+```
+
+只接入 GitHub Server 时使用：
+
+```json
+{
+  "url": "https://tool.cyncyn.xyz/mcp/github",
+  "headers": {
+    "Authorization": "Bearer tch_mcp_..."
+  }
+}
+```
+
+Access Key 只能调用 MCP 数据面，不能读取 Server 或 Credential 配置。Control Key 只能调用控制面，不能作为 MCP 身份使用。
+
+ToolHome 的数据面也实现 OAuth 2.1：Harness 可通过 RFC 9728 元数据发现授权服务器，使用 Authorization Code + PKCE 获取只绑定到具体 MCP endpoint 的 access token。
+
+下游 Dynamic Client Registration 返回由主密钥签名的无状态 Client ID，不依赖进程内注册表；使用同一主密钥重启后仍然有效。同时支持 HTTPS URL-based Client Metadata，并限制响应大小、重定向和非公网目标。
+
+## 上游鉴权
+
+Remote-native Server 支持：
+
+- Bearer token
+- API key header
+- 多个自定义 headers
+- OAuth 2.1 / OIDC
+
+OAuth/OIDC 使用 MCP TypeScript SDK 的官方认证编排器，覆盖 RFC 9728 发现、Authorization Server/OIDC metadata、PKCE、RFC 9207 issuer 校验、CIMD、DCR、刷新和 RFC 8707 resource indicator。OAuth Credential 与一个 Remote Server 一对一绑定，避免 token 跨 resource 或 issuer 复用。
+
+> 若上游授权服务器声明支持 URL-based Client Metadata 但无法从代理域名抓取（例如 Cloudflare 托管的 MCP），可设置 `TOOLHOME_OAUTH_URL_CLIENT_ID=false` 强制使用 Dynamic Client Registration。
+
+Home-hosted Server 使用 Environment Credential 或 transport 自身的 `env`。
+
+Secret 应放入 Credential，而不是 Remote URL query 或 stdio arguments；后两者属于结构配置，无法可靠判断哪些片段需要脱敏。
+
+## CLI
+
+构建后可以运行 `toolhome`；源码开发时使用 `npm run cli --`。
+
+```bash
+export TOOLHOME_URL="https://tool.cyncyn.xyz"
+export TOOLHOME_CONTROL_KEY="tch_ctl_<your-control-key>"
+# 可选：覆盖默认的 ~/.config/toolhome/config.json 路径
+export TOOLHOME_CONFIG="$HOME/.config/toolhome/config.json"
+npm run cli -- auth login
+
+npm run cli -- server list
+npm run cli -- server add ./server.json
+npm run cli -- credential authorize cloudflare
+npm run cli -- access-key create laptop
+npm run cli -- endpoint aggregate
+npm run cli -- doctor
+```
+
+`credential authorize <name>` 按凭据名（或 id）解析，自动在浏览器打开授权链接并保持等待，直到授权成功、失败或超时：
+
+```bash
+npm run cli -- credential authorize notion --server notion   # 指定 server（可省略，自动解析）
+npm run cli -- credential authorize notion --force            # 清掉旧 client 重新授权
+npm run cli -- credential authorize notion --no-open          # 不自动打开浏览器
+npm run cli -- credential authorize notion --no-wait          # 只打印链接，不等待
+npm run cli -- credential authorize notion --timeout 300      # 等待时长（秒，默认 600）
+```
+
+CLI 为每项 Control API 能力提供命令，并保留通用入口：
+
+```bash
+npm run cli -- api GET /api/v1/openapi.json
+```
+
+默认导出只包含可审阅的脱敏配置，不能用于恢复；Credential payload、静态 HTTP Header 值和 stdio transport env 值都会被隐藏。显式包含 Secret 时，CLI 以 `0600` 权限写文件；导入会在一个 SQLite 事务中重建 Credential、重新映射关联 ID，并在任一步失败时整体回滚。
+
+```bash
+npm run cli -- config export backup.json --include-secrets
+npm run cli -- config import backup.json
+```
+
+备份文件包含明文 Secret，应使用与主密钥同等级别的保护。为避免 Secret 意外进入终端日志，`--include-secrets` 必须同时提供目标文件；CLI 会在写入后强制设置 `0600`。日常审阅可省略 `--include-secrets`。
+
+## 配置
+
+| 环境变量                         | 说明                                              | 默认值                  |
+| -------------------------------- | ------------------------------------------------- | ----------------------- |
+| `TOOLHOME_HOST`                  | 监听地址                                          | `127.0.0.1`             |
+| `TOOLHOME_PORT`                  | 监听端口                                          | `3344`                  |
+| `TOOLHOME_PUBLIC_URL`            | 外部可访问的规范 origin，不含 path/query/fragment | `http://127.0.0.1:3344` |
+| `TOOLHOME_DATA_DIR`              | SQLite 与运行数据目录                             | `./data`                |
+| `TOOLHOME_MASTER_KEY`            | Secret 加密、签名与摘要根密钥，至少 32 字符       | 必填                    |
+| `TOOLHOME_BOOTSTRAP_CONTROL_KEY` | 数据库首次启动时写入的 Control Key                | 首次必填                |
+| `TOOLHOME_ALLOWED_HOSTS`         | 允许的 Host，逗号分隔                             | Public URL hostname     |
+| `TOOLHOME_LOG_LEVEL`             | `debug`、`info`、`warn`、`error`                  | `info`                  |
+| `TOOLHOME_WEB_DIR`               | Web 控制台静态文件目录                            | 未启用                  |
+| `TOOLHOME_MARKET_DIR`            | Market npm 安装目录                               | `<dataDir>/market`      |
+| `TOOLHOME_OAUTH_URL_CLIENT_ID`   | 是否启用 URL-based Client Metadata                | `true`                  |
+
+## 安全模型
+
+- 上游 Secret 使用 AES-256-GCM 加密后写入 SQLite。
+- 数据库保存加密的主密钥校验标记；误用不同主密钥时启动会立即失败，避免静默锁死现有 API Key。
+- API Key 只保存 HMAC 摘要，完整 Secret 仅创建时返回。
+- Control 与 MCP Access Key 使用不同前缀和验证域。
+- Web 控制台把 Control Key 换成短期、HttpOnly、SameSite=Strict session cookie。
+- 下游 OAuth token 具有精确 endpoint audience；聚合 token 不能调用独立 endpoint，反之亦然。
+- OAuth callback 校验 state、PKCE、issuer 与发现状态。
+- URL-based client metadata 会拒绝私网和非安全目标，并固定使用已校验的公网解析地址发起 HTTPS 请求，降低 SSRF 与 DNS rebinding 风险。
+- 下游 DCR Client ID 使用主密钥签名，可跨进程重启验证且不在数据库保存 Client Secret。
+- 诊断事件保留最近约 10,000 条；Home-hosted stderr 进入事件流前会按 transport env 与 Environment Credential 值脱敏。
+
+请备份数据库与 `TOOLHOME_MASTER_KEY`，或保存一份受严格保护的 `--include-secrets` 配置导出。丢失主密钥后，原数据库中的加密 Credential 无法恢复。
+
+## 工程命令
+
+```bash
+npm run check
+npm run format:check
+npm run build
+npm run test
+npm run test:real
+```
+
+`npm run test:real` 优先启动构建后的真实 ToolHome 进程，并连接 Home-hosted stdio 与 Remote-native HTTP fixture。它使用官方 MCP Client 验证聚合/独立入口、modern/legacy Harness、Progress、取消、list-changed、MRTR、Tasks 和鉴权边界；没有构建产物时回退到源码入口，便于本地诊断。
+
+`/healthz` 只表示进程存活；`/readyz` 在运行状态不可用时返回 `503`。
+
+## License
+
+[MIT](LICENSE)

package/dist/server/app.d.ts

@@ -0,0 +1,16 @@
+import { type RuntimeConfig } from './config.js';
+import { DataPlane } from './data-plane/data-plane.js';
+import { type Logger } from './observability/logger.js';
+import type { Store } from './storage/store.js';
+import { UpstreamManager } from './upstream/manager.js';
+export interface ApplicationRuntime {
+    app: ReturnType<DataPlane['createApp']>;
+    config: RuntimeConfig;
+    logger: Logger;
+    store: Store;
+    upstreams: UpstreamManager;
+    dataPlane: DataPlane;
+    close(): Promise<void>;
+}
+export declare function createApplication(config?: RuntimeConfig): ApplicationRuntime;
+//# sourceMappingURL=app.d.ts.map

package/dist/server/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAS7D,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAKvD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAYtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAKxD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAkBD,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,aAA4B,GAAG,kBAAkB,CAwJ1F"}