@n24q02m/mcp-core 1.19.0 → 1.20.0-beta.2

package/README.md

@@ -33,6 +33,7 @@
 - [What you get](#what-you-get)
 - [Quick start (Python)](#quick-start-python)
 - [Quick start (TypeScript)](#quick-start-typescript)
+- [CLI](#cli)
 - [Documentation](#documentation)
 - [Development](#development)
 - [License](#license)
@@ -192,6 +193,95 @@ await http.connect()
 // Then mount http.handleRequest(req, res) on your http.Server / Express / Hono.
 ```
 
+## CLI
+
+`mcp_core.cli.build_cli` (re-exported as `from mcp_core import build_cli`) is the
+console-script builder every Python MCP server mounts as its entry point. It wraps
+a server's existing `serve(argv) -> int | None` function with subcommand dispatch,
+so every server exposes the **same** operator subcommands for free while `serve`'s
+own behaviour stays byte-for-byte unchanged. It has no TypeScript counterpart.
+
+A downstream server mounts it as its console script:
+
+```python
+# wet_mcp/cli.py
+from mcp_core import build_cli
+
+def main() -> int:
+    return build_cli("wet-mcp", serve=_serve, extra=_extras(), version=_version())(None)
+```
+
+```toml
+# pyproject.toml
+[project.scripts]
+wet-mcp = "wet_mcp.cli:main"
+```
+
+### Dispatch rules
+
+`build_cli(...)` returns `run(argv=None) -> int`, which inspects `argv[0]`:
+
+- **No args** — start the server (`serve([])`), the normal stdio launch.
+- **A flag** (`--http`, ...) — passed byte-for-byte to `serve`; existing flag
+  semantics are untouched.
+- **`-h` / `--help`** — print the subcommand list and exit without starting the
+  server (which would otherwise hang waiting on stdin in stdio mode).
+- **`--version` / `-V`** — print `<server> <version>`, but only when `version=` is
+  passed; otherwise it falls through to `serve` like any other flag.
+- **A positional name** — routed as a subcommand through argparse; an unknown name
+  exits `2`.
+
+STDOUT is the MCP protocol channel in stdio mode, so only the subcommand path prints
+to stdout: informational results (status, session details, `doctor`'s
+`[ok]`/`[warn]`/`[fail]` lines) go to stdout, while failures and prompts go to stderr
+with a non-zero exit code. Credential **values** are never printed — only names, keys,
+and status.
+
+### Built-in subcommands
+
+Every server gets three reserved subcommands without writing any code:
+
+| Subcommand | Purpose |
+|---|---|
+| `config status` | Report whether a config is stored: `configured`, `not configured`, or `corrupt` (undecryptable). |
+| `config delete [--yes]` | Delete the stored config. Prompts to confirm; `--yes` skips the prompt and is required in non-interactive mode. |
+| `relay status` | Show the active relay session (id prefix, relay URL, age) or report that none is active. |
+| `relay open` | Open the active relay URL in a browser. |
+| `relay reset` | Clear the relay session lock and the stored transport mode. |
+| `doctor` | Environment diagnostics — Python 3.13, credential-backend init, store-dir writability, config state, relay session, transport mode. Exits non-zero on any `[fail]`. |
+
+```bash
+wet-mcp doctor
+wet-mcp config status
+wet-mcp relay status
+```
+
+### Server-specific subcommands (`extra`)
+
+`build_cli(..., extra=...)` adds server-specific subcommands. Names in `extra` take
+precedence over the built-ins, so a server can replace `config` / `relay` / `doctor`
+with its own wiring. Each `extra` value is one of two shapes:
+
+```python
+ExtraHandler = Callable[[argparse.Namespace], int]
+ExtraSpec = ExtraHandler | tuple[Callable[[argparse.ArgumentParser], None], ExtraHandler]
+```
+
+- A **bare handler** — registered as an argument-less subcommand.
+- A **`(configure, handler)` tuple** — `configure` receives that subcommand's own
+  `argparse.ArgumentParser` to add positionals/flags before argv is parsed, then
+  `handler` receives the parsed `Namespace` and returns the exit code.
+
+wet-mcp, for example, registers one bare handler and two configured ones:
+
+```python
+extra = {
+    "warmup": _handle_warmup,                 # wet-mcp warmup
+    "auth": (_configure_auth, _handle_auth),  # wet-mcp auth google [--client-id ...]
+    "docs": (_configure_docs, _handle_docs),  # wet-mcp docs reindex <library>
+}
+```
+
 ## Documentation
 
 Full docs at **[mcp.n24q02m.com/servers/mcp-core/architecture/](https://mcp.n24q02m.com/servers/mcp-core/architecture/)** (Foundation library section in the MCP n24q02m unified docs site):
@@ -225,4 +315,4 @@ bun run build
 
 ## License
 
-MIT
+MIT

package/build/auth/credential-form.d.ts

@@ -16,6 +16,8 @@ export interface ConfigField {
     helpText?: string;
     helpUrl?: string;
     required?: boolean;
+    /** Regex string for client-side validation; rendered as the input's `pattern` attribute. */
+    validation?: string;
 }
 /**
  * Return true iff every required field in `schema` has a non-empty value in
@@ -32,12 +34,39 @@ export interface CapabilityInfo {
     priority?: string;
     description?: string;
 }
+/**
+ * A credential-form tab (schema-level `tabs` capability). Each tab is a
+ * mutually-exclusive credential mode; only the active tab's fields submit.
+ */
+export interface TabGroup {
+    id: string;
+    label: string;
+    fields: ConfigField[];
+}
+/**
+ * A repeatable field group (schema-level `cardGroup` capability). Renders
+ * Add/Remove cards, each cloning `fields`; submitted as a JSON array under
+ * `key` (e.g. `{ accounts: [{...}, {...}] }`).
+ */
+export interface CardGroup {
+    key: string;
+    fields: ConfigField[];
+    itemLabel?: string;
+    heading?: string;
+    addButtonLabel?: string;
+    minItems?: number;
+    titleField?: string;
+}
 export interface RelayConfigSchema {
     server: string;
     displayName?: string;
     description?: string;
-    fields: ConfigField[];
+    fields?: ConfigField[];
     capabilityInfo?: CapabilityInfo[];
+    /** Mutually-exclusive credential modes; see the tabbed render path. */
+    tabs?: TabGroup[];
+    /** One repeatable field group; see the card-group render path. */
+    cardGroup?: CardGroup;
 }
 export interface RenderOptions {
     submitUrl: string;
@@ -50,14 +79,29 @@ export interface RenderOptions {
      * keys are ignored.
      */
     prefill?: Record<string, string>;
+    /**
+     * For a `tabs` schema, the id of the tab to render active on load (defaults
+     * to the first tab). Ignored for non-tabbed schemas.
+     */
+    initialTab?: string;
+    /**
+     * Opt-in workspace-username field (multi-user stable-sub). Honoured by the
+     * flat, `tabs`, and `cardGroup` render paths.
+     */
+    includeUsernameField?: boolean;
 }
 /**
  * Wrap `bodyHtml` in the shared dark-theme HTML shell.
  *
- * The shell provides `<!DOCTYPE html>`, `<head>` (charset, viewport, escaped
- * `<title>`, embedded `FORM_SHELL_CSS`) and a `<body>` whose only child is
- * `bodyHtml`. `bodyHtml` is inserted verbatim, so callers MUST pre-escape any
- * untrusted values they interpolate.
+ * The shell provides `<!DOCTYPE html>`, `<head>` (charset, viewport, a
+ * Content-Security-Policy meta, escaped `<title>`, embedded `FORM_SHELL_CSS`)
+ * and a `<body>` whose only child is `bodyHtml`. `bodyHtml` is inserted
+ * verbatim, so callers MUST pre-escape any untrusted values they interpolate.
+ *
+ * The CSP (`default-src 'none'; style-src 'unsafe-inline'; script-src
+ * 'unsafe-inline'; connect-src 'self'`) permits the page's own inline
+ * `<style>`/`<script>` and same-origin `fetch` submits while blocking any
+ * external resource load.
  *
  * `title` is HTML-escaped before being placed in `<title>`.
  *

package/build/auth/credential-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credential-form.d.ts","sourceRoot":"","sources":["../../src/auth/credential-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAqBT;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,cAAc,CAAC,EAAE,cAAc,EAAE,CAAA;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAqWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAevE;AAqED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAia9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,OAAO,CAAA;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"credential-form.d.ts","sourceRoot":"","sources":["../../src/auth/credential-form.ts"],"names":[],"mappings":"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"}