@belgie/mcp 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# `@belgie/mcp`
+
+TypeScript helpers for building Belgie MCP Apps, generating typed MCP tool callers, and packaging path-based React
+widgets with Vite.
+
+## Installation
+
+Install the package and its MCP Apps peer dependency with npm:
+
+```sh
+npm install @belgie/mcp @modelcontextprotocol/ext-apps
+```
+
+Install Vite when using the widget plugin:
+
+```sh
+npm install --save-dev vite
+```
+
+## Package exports
+
+- `@belgie/mcp` exports `Widget`, `mountWidget`, `useWidget`, `useToolResult`, context-bound App helpers, and MCP tool
+  errors.
+- `@belgie/mcp/codegen` exports programmatic MCP tool-type generation.
+- `@belgie/mcp/internal` contains the runtime factories used by generated callers.
+- `@belgie/mcp/vite` exports the `belgie()` Vite plugin.
+- `@belgie/mcp/package.json` exposes the package metadata.
+
+The package is ESM-only and requires Node.js 22 or newer.
+
+## Generate typed tool callers
+
+Run the CLI against a streamable HTTP MCP endpoint:
+
+```sh
+npx belgie-mcp generate https://example.com/mcp --output src/mcp-tools.ts
+```
+
+OAuth is enabled by default. Use `--no-oauth` for an endpoint that does not require it, `--no-open` to print the
+authorization URL, `--header NAME:VALUE` for a direct header, or `--header-env NAME=ENV_VAR` to read a secret from the
+environment. `--check` verifies that an existing output file is current without rewriting it.
+
+Generated callers execute only when called, use the connected widget App by default, and accept an explicit App as the
+optional second argument:
+
+```ts
+import { getWeather } from "./mcp-tools.ts";
+
+const { result, error } = await getWeather({ city: "Austin" });
+```
+
+## Build a widget
+
+Widgets are discovered at `<srcDir>/<name>/widget.tsx` and must have a default export:
+
+```tsx
+import { Widget, mountWidget, useToolResult } from "@belgie/mcp";
+import { getWeather } from "../../../mcp-tools.ts";
+
+function Weather() {
+  const weather = useToolResult(getWeather);
+  return (
+    <Widget metadata={{ name: "weather", version: "1.0.0" }}>
+      {weather.data?.summary ?? "Waiting for weather"}
+    </Widget>
+  );
+}
+
+mountWidget(Weather);
+```
+
+Add the plugin to a normal Vite configuration. Development serves each widget at `/widgets/<name>/index.html`;
+production emits a self-contained `dist/widgets/<name>/index.html` with JavaScript, CSS, and assets inlined.
+
+```ts
+import { defineConfig } from "vite";
+import { belgie } from "@belgie/mcp/vite";
+
+export default defineConfig({
+  plugins: [belgie({ srcDir: "src/widgets" })],
+});
+```
+
+## Development
+
+This package uses npm and keeps its lockfile in version control:
+
+```sh
+npm ci
+npm run dev
+npm run check
+npm run test:watch
+npm test
+npm pack --dry-run
+```
+
+`npm test` builds with tsdown, validates the package with publint and `@arethetypeswrong/cli` rules, runs the serialized
+Vitest suite with V8 coverage, and checks TypeScript 7 declarations and API fixtures.

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+//#region src/cli.d.ts
+declare function values(value: string | string[] | undefined): string[];
+declare function parseHeader(value: string): [string, string];
+declare function parseEnvironmentHeader(value: string): [string, string];
+declare function runCli(args?: string[]): Promise<void>;
+declare function isDirectExecution(moduleUrl: string, executable: string | undefined): boolean;
+declare function reportCliError(cause: unknown): void;
+//#endregion
+export { isDirectExecution, parseEnvironmentHeader, parseHeader, reportCliError, runCli, values };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { t as generateToolTypes } from "./codegen-DnMS1wg_.js";
+import { realpathSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+const USAGE = `Usage:
+  belgie-mcp generate <url> --output <file> [options]
+
+Options:
+  --check                    Fail when the output file is missing or stale
+  --header NAME:VALUE        Add an introspection header (repeatable)
+  --header-env NAME=ENV_VAR  Read a header value from the environment (repeatable)
+  --no-oauth                 Disable automatic OAuth discovery and PKCE
+  --no-open                  Print the OAuth URL instead of opening a browser
+`;
+function values(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function parseHeader(value) {
+	const separator = value.indexOf(":");
+	if (separator <= 0) throw new Error(`Invalid --header ${JSON.stringify(value)}; expected NAME:VALUE`);
+	const name = value.slice(0, separator).trim();
+	const headerValue = value.slice(separator + 1).trim();
+	if (name.length === 0 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name)) throw new Error(`Invalid header name ${JSON.stringify(name)}`);
+	return [name, headerValue];
+}
+function parseEnvironmentHeader(value) {
+	const separator = value.indexOf("=");
+	if (separator <= 0 || separator === value.length - 1) throw new Error(`Invalid --header-env ${JSON.stringify(value)}; expected NAME=ENV_VAR`);
+	const name = value.slice(0, separator).trim();
+	const environmentName = value.slice(separator + 1).trim();
+	if (name.length === 0 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name)) throw new Error(`Invalid header name ${JSON.stringify(name)}`);
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(environmentName)) throw new Error(`Invalid environment variable name ${JSON.stringify(environmentName)}`);
+	const headerValue = process.env[environmentName];
+	if (headerValue === void 0) throw new Error(`Environment variable ${environmentName} is not set`);
+	return [name, headerValue];
+}
+async function runCli(args = process.argv.slice(2)) {
+	const { positionals, values: options } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {
+			check: {
+				type: "boolean",
+				default: false
+			},
+			header: {
+				type: "string",
+				multiple: true
+			},
+			"header-env": {
+				type: "string",
+				multiple: true
+			},
+			"no-oauth": {
+				type: "boolean",
+				default: false
+			},
+			"no-open": {
+				type: "boolean",
+				default: false
+			},
+			output: {
+				type: "string",
+				short: "o"
+			}
+		},
+		strict: true
+	});
+	if (positionals[0] !== "generate" || positionals.length !== 2) throw new Error(USAGE);
+	if (options.output === void 0) throw new Error(`--output is required\n\n${USAGE}`);
+	const headers = Object.fromEntries([...values(options.header).map(parseHeader), ...values(options["header-env"]).map(parseEnvironmentHeader)]);
+	const output = resolve(options.output);
+	const generated = await generateToolTypes({
+		url: positionals[1],
+		headers,
+		oauth: !options["no-oauth"],
+		openBrowser: !options["no-open"]
+	});
+	if (options.check) {
+		let current;
+		try {
+			current = await readFile(output, "utf8");
+		} catch (cause) {
+			if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT")) throw cause;
+		}
+		if (current !== generated) throw new Error(`Generated MCP tool types are stale or missing: ${output}`);
+		process.stdout.write(`MCP tool types are current: ${output}\n`);
+		return;
+	}
+	await mkdir(dirname(output), { recursive: true });
+	await writeFile(output, generated, "utf8");
+	process.stdout.write(`Generated MCP tool types: ${output}\n`);
+}
+function isDirectExecution(moduleUrl, executable) {
+	if (executable === void 0) return false;
+	const executionPath = (value) => {
+		try {
+			return realpathSync(value);
+		} catch {
+			return resolve(value);
+		}
+	};
+	return executionPath(executable) === executionPath(fileURLToPath(moduleUrl));
+}
+function reportCliError(cause) {
+	const message = cause instanceof Error ? cause.message : String(cause);
+	process.stderr.write(`${message}\n`);
+	process.exitCode = 1;
+}
+if (isDirectExecution(import.meta.url, process.argv[1])) runCli().catch(reportCliError);
+//#endregion
+export { isDirectExecution, parseEnvironmentHeader, parseHeader, reportCliError, runCli, values };
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { realpathSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { parseArgs } from \"node:util\";\n\nimport { generateToolTypes } from \"./codegen\";\n\nconst USAGE = `Usage:\n  belgie-mcp generate <url> --output <file> [options]\n\nOptions:\n  --check                    Fail when the output file is missing or stale\n  --header NAME:VALUE        Add an introspection header (repeatable)\n  --header-env NAME=ENV_VAR  Read a header value from the environment (repeatable)\n  --no-oauth                 Disable automatic OAuth discovery and PKCE\n  --no-open                  Print the OAuth URL instead of opening a browser\n`;\n\nexport function values(value: string | string[] | undefined): string[] {\n  if (value === undefined) {\n    return [];\n  }\n  return Array.isArray(value) ? value : [value];\n}\n\nexport function parseHeader(value: string): [string, string] {\n  const separator = value.indexOf(\":\");\n  if (separator <= 0) {\n    throw new Error(`Invalid --header ${JSON.stringify(value)}; expected NAME:VALUE`);\n  }\n  const name = value.slice(0, separator).trim();\n  const headerValue = value.slice(separator + 1).trim();\n  if (name.length === 0 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name)) {\n    throw new Error(`Invalid header name ${JSON.stringify(name)}`);\n  }\n  return [name, headerValue];\n}\n\nexport function parseEnvironmentHeader(value: string): [string, string] {\n  const separator = value.indexOf(\"=\");\n  if (separator <= 0 || separator === value.length - 1) {\n    throw new Error(\n      `Invalid --header-env ${JSON.stringify(value)}; expected NAME=ENV_VAR`,\n    );\n  }\n  const name = value.slice(0, separator).trim();\n  const environmentName = value.slice(separator + 1).trim();\n  if (name.length === 0 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name)) {\n    throw new Error(`Invalid header name ${JSON.stringify(name)}`);\n  }\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(environmentName)) {\n    throw new Error(`Invalid environment variable name ${JSON.stringify(environmentName)}`);\n  }\n  const headerValue = process.env[environmentName];\n  if (headerValue === undefined) {\n    throw new Error(`Environment variable ${environmentName} is not set`);\n  }\n  return [name, headerValue];\n}\n\nexport async function runCli(args: string[] = process.argv.slice(2)): Promise<void> {\n  const { positionals, values: options } = parseArgs({\n    args,\n    allowPositionals: true,\n    options: {\n      check: { type: \"boolean\", default: false },\n      header: { type: \"string\", multiple: true },\n      \"header-env\": { type: \"string\", multiple: true },\n      \"no-oauth\": { type: \"boolean\", default: false },\n      \"no-open\": { type: \"boolean\", default: false },\n      output: { type: \"string\", short: \"o\" },\n    },\n    strict: true,\n  });\n\n  if (positionals[0] !== \"generate\" || positionals.length !== 2) {\n    throw new Error(USAGE);\n  }\n  if (options.output === undefined) {\n    throw new Error(`--output is required\\n\\n${USAGE}`);\n  }\n\n  const headers = Object.fromEntries([\n    ...values(options.header).map(parseHeader),\n    ...values(options[\"header-env\"]).map(parseEnvironmentHeader),\n  ]);\n  const output = resolve(options.output);\n  const generated = await generateToolTypes({\n    url: positionals[1]!,\n    headers,\n    oauth: !options[\"no-oauth\"],\n    openBrowser: !options[\"no-open\"],\n  });\n\n  if (options.check) {\n    let current: string | undefined;\n    try {\n      current = await readFile(output, \"utf8\");\n    } catch (cause: unknown) {\n      if (!(cause instanceof Error && \"code\" in cause && cause.code === \"ENOENT\")) {\n        throw cause;\n      }\n    }\n    if (current !== generated) {\n      throw new Error(`Generated MCP tool types are stale or missing: ${output}`);\n    }\n    process.stdout.write(`MCP tool types are current: ${output}\\n`);\n    return;\n  }\n\n  await mkdir(dirname(output), { recursive: true });\n  await writeFile(output, generated, \"utf8\");\n  process.stdout.write(`Generated MCP tool types: ${output}\\n`);\n}\n\nexport function isDirectExecution(moduleUrl: string, executable: string | undefined): boolean {\n  if (executable === undefined) {\n    return false;\n  }\n  const executionPath = (value: string) => {\n    try {\n      return realpathSync(value);\n    } catch {\n      return resolve(value);\n    }\n  };\n  return executionPath(executable) === executionPath(fileURLToPath(moduleUrl));\n}\n\nexport function reportCliError(cause: unknown): void {\n  const message = cause instanceof Error ? cause.message : String(cause);\n  process.stderr.write(`${message}\\n`);\n  process.exitCode = 1;\n}\n\nif (isDirectExecution(import.meta.url, process.argv[1])) {\n  runCli().catch(reportCliError);\n}\n"],"mappings":";;;;;;;;AAUA,MAAM,QAAQ;;;;;;;;;;AAWd,SAAgB,OAAO,OAAgD;CACrE,IAAI,UAAU,KAAA,GACZ,OAAO,CAAC;CAEV,OAAO,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;AAC9C;AAEA,SAAgB,YAAY,OAAiC;CAC3D,MAAM,YAAY,MAAM,QAAQ,GAAG;CACnC,IAAI,aAAa,GACf,MAAM,IAAI,MAAM,oBAAoB,KAAK,UAAU,KAAK,EAAE,sBAAsB;CAElF,MAAM,OAAO,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,KAAK;CAC5C,MAAM,cAAc,MAAM,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;CACpD,IAAI,KAAK,WAAW,KAAK,CAAC,iCAAiC,KAAK,IAAI,GAClE,MAAM,IAAI,MAAM,uBAAuB,KAAK,UAAU,IAAI,GAAG;CAE/D,OAAO,CAAC,MAAM,WAAW;AAC3B;AAEA,SAAgB,uBAAuB,OAAiC;CACtE,MAAM,YAAY,MAAM,QAAQ,GAAG;CACnC,IAAI,aAAa,KAAK,cAAc,MAAM,SAAS,GACjD,MAAM,IAAI,MACR,wBAAwB,KAAK,UAAU,KAAK,EAAE,wBAChD;CAEF,MAAM,OAAO,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,KAAK;CAC5C,MAAM,kBAAkB,MAAM,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;CACxD,IAAI,KAAK,WAAW,KAAK,CAAC,iCAAiC,KAAK,IAAI,GAClE,MAAM,IAAI,MAAM,uBAAuB,KAAK,UAAU,IAAI,GAAG;CAE/D,IAAI,CAAC,4BAA4B,KAAK,eAAe,GACnD,MAAM,IAAI,MAAM,qCAAqC,KAAK,UAAU,eAAe,GAAG;CAExF,MAAM,cAAc,QAAQ,IAAI;CAChC,IAAI,gBAAgB,KAAA,GAClB,MAAM,IAAI,MAAM,wBAAwB,gBAAgB,YAAY;CAEtE,OAAO,CAAC,MAAM,WAAW;AAC3B;AAEA,eAAsB,OAAO,OAAiB,QAAQ,KAAK,MAAM,CAAC,GAAkB;CAClF,MAAM,EAAE,aAAa,QAAQ,YAAY,UAAU;EACjD;EACA,kBAAkB;EAClB,SAAS;GACP,OAAO;IAAE,MAAM;IAAW,SAAS;GAAM;GACzC,QAAQ;IAAE,MAAM;IAAU,UAAU;GAAK;GACzC,cAAc;IAAE,MAAM;IAAU,UAAU;GAAK;GAC/C,YAAY;IAAE,MAAM;IAAW,SAAS;GAAM;GAC9C,WAAW;IAAE,MAAM;IAAW,SAAS;GAAM;GAC7C,QAAQ;IAAE,MAAM;IAAU,OAAO;GAAI;EACvC;EACA,QAAQ;CACV,CAAC;CAED,IAAI,YAAY,OAAO,cAAc,YAAY,WAAW,GAC1D,MAAM,IAAI,MAAM,KAAK;CAEvB,IAAI,QAAQ,WAAW,KAAA,GACrB,MAAM,IAAI,MAAM,2BAA2B,OAAO;CAGpD,MAAM,UAAU,OAAO,YAAY,CACjC,GAAG,OAAO,QAAQ,MAAM,CAAC,CAAC,IAAI,WAAW,GACzC,GAAG,OAAO,QAAQ,aAAa,CAAC,CAAC,IAAI,sBAAsB,CAC7D,CAAC;CACD,MAAM,SAAS,QAAQ,QAAQ,MAAM;CACrC,MAAM,YAAY,MAAM,kBAAkB;EACxC,KAAK,YAAY;EACjB;EACA,OAAO,CAAC,QAAQ;EAChB,aAAa,CAAC,QAAQ;CACxB,CAAC;CAED,IAAI,QAAQ,OAAO;EACjB,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,SAAS,QAAQ,MAAM;EACzC,SAAS,OAAgB;GACvB,IAAI,EAAE,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,WAChE,MAAM;EAEV;EACA,IAAI,YAAY,WACd,MAAM,IAAI,MAAM,kDAAkD,QAAQ;EAE5E,QAAQ,OAAO,MAAM,+BAA+B,OAAO,GAAG;EAC9D;CACF;CAEA,MAAM,MAAM,QAAQ,MAAM,GAAG,EAAE,WAAW,KAAK,CAAC;CAChD,MAAM,UAAU,QAAQ,WAAW,MAAM;CACzC,QAAQ,OAAO,MAAM,6BAA6B,OAAO,GAAG;AAC9D;AAEA,SAAgB,kBAAkB,WAAmB,YAAyC;CAC5F,IAAI,eAAe,KAAA,GACjB,OAAO;CAET,MAAM,iBAAiB,UAAkB;EACvC,IAAI;GACF,OAAO,aAAa,KAAK;EAC3B,QAAQ;GACN,OAAO,QAAQ,KAAK;EACtB;CACF;CACA,OAAO,cAAc,UAAU,MAAM,cAAc,cAAc,SAAS,CAAC;AAC7E;AAEA,SAAgB,eAAe,OAAsB;CACnD,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CACrE,QAAQ,OAAO,MAAM,GAAG,QAAQ,GAAG;CACnC,QAAQ,WAAW;AACrB;AAEA,IAAI,kBAAkB,OAAO,KAAK,KAAK,QAAQ,KAAK,EAAE,GACpD,OAAO,CAAC,CAAC,MAAM,cAAc"}