From f62795aa113b00a35afea6dd9b6430c4fd652882 Mon Sep 17 00:00:00 2001
From: EthanHuo <huodong.work@gmail.com>
Date: Fri, 13 Nov 2026 01:27:10 +0800
Subject: [PATCH] docs(schema): describe @add fields, quote @ selectors in the
 guide, hide @daemon.server (0.18.2)

---
 package.json  |  2 +-
 src/index.md  | 10 +++++-----
 src/router.ts | 33 +++++++++++++++++++++++++++------
 3 files changed, 33 insertions(+), 12 deletions(-)

diff --git a/package.json b/package.json
index c393acb..f1a3f31 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "mcpx",
-	"version": "0.18.1",
+	"version": "0.18.2",
 	"license": "MIT",
 	"bin": {
 		"mcpx": "./src/main.ts"
diff --git a/src/index.md b/src/index.md
index 38e6b56..3792b1c 100644
--- a/src/index.md
+++ b/src/index.md
@@ -17,18 +17,18 @@ The surface depends on the registry, so read only the slice you need: `mcpx @sch
 ## Calling a tool — `.<server>.<tool>`
 
 - Call as `mcpx <server>.<tool> "<object>"`. The object is the complete tool input: one quoted token, or the whole object as YAML/JSON5 from `@file` or stdin (`-`).
-- Put multi-line text in a quoted heredoc with `|` block scalars. Field values are literal: never pass `-` or `@path` as a field value, and never mix the object with `--flag`s. Quote scalars YAML would retype (`'1.10'`, `'012'`, `'true'`). A file or stdin starting with `{` is read as JSON5.
+- Put multi-line text in a quoted heredoc with `|` block scalars. Field values are literal: no field takes `-` or `@path`. Quote scalars YAML would retype (`'1.10'`, `'012'`, `'true'`). A file or stdin starting with `{` is read as JSON5.
 - Tool results may include `$notifications` (progress, server events). Ignore them unless the task depends on them; format and special cases: `mcpx @skill references/notifications.md`.
 
-## Registering servers — `@add`, `@login`, `@remove`
+## Registering servers — `.{"@add","@login","@remove"}` (quote the `@`)
 
-Only when the user asks. `@add` takes an HTTP `url` (default) or `transport: 'stdio'` with `command`/`args`; after that both behave identically. Bearer auth goes in `bearer`, and `env:NAME` keeps the secret out of the registry (an array round-robins credentials). `@login "{ name: '<server>' }"` needs a TTY; otherwise ask the user to run it. Input shapes: `mcpx @add --help`.
+Only when the user asks. After `@add`, HTTP and stdio servers behave identically. Register a bearer token as `env:NAME` so the secret stays out of the registry and argv. `@login "{ name: '<server>' }"` needs a TTY; otherwise ask the user to run it.
 
-## Project-local skills — `@skill-install`
+## Project-local skills — `."@skill-install"`
 
 When the user wants a project to expose only an approved set of servers, `mcpx @skill-install "{ servers: 'posthog,sentry' }"` writes `.agents/skills/mcpx/` (router plus install and server-recovery references). `{ show: 'sentry' }` prints a one-server skill to stdout without writing files. It does not replace `@add`.
 
-## Daemon — `@daemon`
+## Daemon — `."@daemon"`
 
 `mcpxd` keeps sessions warm and is normally invisible. For stuck sessions, surprising eviction or schema drift read `mcpx @skill references/daemon.md` before filing an issue.
 
diff --git a/src/router.ts b/src/router.ts
index c699e16..e5b9951 100644
--- a/src/router.ts
+++ b/src/router.ts
@@ -64,7 +64,12 @@ const outputContext = s(
 const addInput = s(
 	v.object({
 		name: v.pipe(v.string(), v.description('Global server name')),
-		transport: v.optional(v.picklist(['http', 'stdio'])),
+		transport: v.optional(
+			v.pipe(
+				v.picklist(['http', 'stdio']),
+				v.description('Default http; stdio needs command'),
+			),
+		),
 		url: v.optional(
 			v.pipe(
 				v.string(),
@@ -72,12 +77,29 @@ const addInput = s(
 				v.description('MCP Streamable HTTP endpoint URL'),
 			),
 		),
-		bearer: v.optional(v.union([v.string(), v.array(v.string())])),
+		bearer: v.optional(
+			v.pipe(
+				v.union([v.string(), v.array(v.string())]),
+				v.description(
+					"Token or env reference ('env:NAME', kept live); several round-robin. Prefer env:NAME, or pass the object via stdin so a literal stays off argv",
+				),
+			),
+		),
 		command: v.optional(
 			v.pipe(v.string(), v.description('Stdio MCP server command')),
 		),
-		args: v.optional(v.union([v.string(), v.array(v.string())])),
-		env: v.optional(v.record(v.string(), v.string())),
+		args: v.optional(
+			v.pipe(
+				v.union([v.string(), v.array(v.string())]),
+				v.description('Stdio command arguments'),
+			),
+		),
+		env: v.optional(
+			v.pipe(
+				v.record(v.string(), v.string()),
+				v.description('Environment for the stdio process'),
+			),
+		),
 	}),
 )
 
@@ -234,7 +256,6 @@ function buildRouter(registry: RegistryView, schemas?: SchemaResync): Router {
 		'@remove': c
 			.meta({
 				description: 'Remove a global MCP server and its cached credentials.',
-				examples: [`mcpx @remove "{ name: 'posthog,sentry' }"`],
 			})
 			.input(removeInput),
 		'@login': c
@@ -254,6 +275,7 @@ function buildRouter(registry: RegistryView, schemas?: SchemaResync): Router {
 				}),
 				server: c.meta({
 					description: 'Run the local mcpxd daemon server.',
+					hidden: true,
 				}),
 			},
 		),
@@ -261,7 +283,6 @@ function buildRouter(registry: RegistryView, schemas?: SchemaResync): Router {
 			.meta({
 				description:
 					'Generate a project skill or print a temporary server skill for agents.',
-				examples: [`mcpx @skill-install "{ servers: 'posthog,sentry' }"`],
 			})
 			.input(skillInput),
 	}