From c523b940c52d5a37cb696abf366eafdffcc27cfa Mon Sep 17 00:00:00 2001 From: Willie Date: Wed, 30 Sep 2026 11:52:33 +0800 Subject: [PATCH] docs(mcp): document mcp check Users and agents need to know what the check verifies, which findings fail it, and the JSON shape scripts can rely on. English only; translations are left for a follow-up. --- skills/skillshare/references/mcp.md | 4 ++ website/docs/reference/commands/mcp.md | 51 ++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index a6d1a67df..5a4b60833 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -19,6 +19,7 @@ skillshare mcp remove docs --sync --no-tui # Remove unchanged managed skillshare mcp remove docs --keep-files --no-tui # Stop managing; Agent entries stay as they are skillshare mcp restore BACKUP_ID --dry-run --json # Preview entry-level restoration skillshare mcp restore BACKUP_ID --no-tui # Apply restoration; source stays unchanged +skillshare mcp check --json # Static check: variables, commands, DNS, sync state ``` ## Automation rules @@ -36,6 +37,9 @@ skillshare mcp restore BACKUP_ID --no-tui # Apply restoration; source `--pi-options` or `-- command args`. Switching transport clears the fields of the other one. - Preview with `skillshare sync mcp --dry-run --json`, then apply with `skillshare sync mcp --revision ` to reject a stale plan. +- `mcp check [name...] [--json] [--no-dns]` is read-only and starts nothing. It exits 1 + on an error (unset `fromEnv` variable, command not on PATH, client rule, conflict); + an unresolved host or an unsynced entry is only a warning. - Noninteractive `import` without a name only lists candidates. Use `--replace` only when replacing is intended. - An `update` with the message `same settings, laid out one field per line` is a diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index 44752d17a..0a2cd4d6c 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -19,6 +19,8 @@ skillshare mcp add local --target codex -- company-mcp --workspace /path/to/work skillshare mcp import docs --from claude --target claude --target cursor --sync skillshare mcp import docs --file ./provider.json --target claude skillshare mcp list --json +skillshare mcp check +skillshare mcp check docs --json --no-dns skillshare mcp remove docs --sync skillshare mcp remove docs --keep-files skillshare mcp restore BACKUP_ID --dry-run @@ -44,6 +46,7 @@ skillshare sync --all | `--replace` | Explicitly replace an existing source definition during add/import; on import, also rewrite the imported client's entry when it differs | | `--dry-run`, `-n` | Preview without saving or writing native configuration | | `--json` | Structured output; sync/preview reports contain names, paths and actions, not server values | +| `--no-dns` | With `check`: skip the host lookup of remote servers. See [below](#check-servers-before-an-agent-starts-them) | | `--no-tui` | Disable interactive menus; also disabled by `tui: false`, `--json`, or non-terminal input/output | | `--revision ID` | Require a matching preview for add/import/remove or `sync mcp` | | `--global`, `-g` | Use global Skillshare configuration | @@ -583,6 +586,54 @@ Limits: - If a folder also has its own `.skillshare/config.yaml` managing the same entry, the plan reports a conflict rather than overwriting it. +## Check servers before an Agent starts them {#check-servers-before-an-agent-starts-them} + +```bash +skillshare mcp check +skillshare mcp check docs github --json +skillshare mcp check --no-dns +``` + +`mcp check` answers "will this server work as synced?" for every server in the +source, or only the named ones. It is read-only: it never starts a server, sends an +HTTP request, runs a command or writes a file. + +| Check | Level | +|---|---| +| A `fromEnv` variable in `env`, `headers` or `bearerToken` is unset or empty | error | +| A local server's `command` is not found on `PATH` (a leading `~/` is expanded) | error | +| A remote server's host does not resolve through DNS (3-second limit; skip with `--no-dns`) | warning | +| An Agent's rule refuses the server, such as a name Claude Code reserves | error | +| An Agent's entry conflicts with the source, as in `sync mcp --dry-run` | error | +| An Agent's entry is not written or not updated yet | warning | +| The server has `targets: []` and is kept in Skillshare only | info | + +Variable values are never printed. The command exits with 1 when any error is found +and 0 otherwise; warnings never fail it. An unknown server name is an error that +lists the known names. Servers under `mcp.projects` are not checked. + +With `--json`, the report has this shape: + +```json +{ + "servers": [ + { + "name": "docs", + "ok": false, + "findings": [ + { "level": "error", "check": "env", "target": "", "message": "bearerToken reads DOCS_TOKEN, which is not set" }, + { "level": "warning", "check": "sync", "target": "claude", "message": "not synced yet; run skillshare sync mcp" } + ] + } + ], + "summary": { "errors": 1, "warnings": 1 } +} +``` + +`check` is one of `env`, `command`, `url`, `dns`, `client-rule`, `sync` or `targets`. +`target` names the Agent or account, and is empty when the finding is about the +server itself. + ## Stop managing a server {#stop-managing-a-server} ```bash