# Your website, your catalog

Delight 0.2 serves your public data through MCP, WebMCP and MCP Apps. Supply a JSON file; no package source edits are required. Requires Node.js 22+ for setup and MCP hosting. The exported website runs without a Node server.

## Create and run

```sh
npx delight-mcp@0.2.0 --init-config delight.config.json
# Edit the generated example with your content, links and colors.
npx delight-mcp@0.2.0 --check-config delight.config.json
npx delight-mcp@0.2.0 --config delight.config.json
```

Open http://127.0.0.1:3001. Search for `*` to browse your catalog. The MCP endpoint is http://127.0.0.1:3001/mcp. Initialization never overwrites an existing file. Invalid configuration stops startup with a field-specific error; it never silently falls back to the reference data. With no configuration, the CLI runs the original Full Iron demo.

The generated file includes a `$schema` link for editor completion and field validation. The schema is generated from the same definition as runtime validation. To keep a local copy:

```sh
npx delight-mcp@0.2.0 --print-schema > delight.schema.json
```

Set `$schema` to `./delight.schema.json` when using that local copy. Save configuration files as UTF-8; a UTF-8 BOM is accepted. Editor validation helps with structure; `--check-config` also checks unique IDs, safe URLs, color contrast and the total size. The package never fetches the `$schema` address at runtime.

## Guided setup and diagnostics (0.3 preview)

`setup` and `doctor` are being prepared for 0.3.0; they are not available in the published 0.2.0 package. In the source checkout, run `npm run build` in `agent-server`, then use `node cli.mjs` as shown below. Generated next-step commands target the forthcoming npm version; use `node cli.mjs` in their place until that version is published.

```sh
node cli.mjs setup
```

The wizard asks for a source, website name, accent, background, text color and a new output filename. The source can be an existing Delight JSON file or a public HTTPS URL returning that format. A blank source uses fictional starter data; replace its entries and links before publishing. Setup imports a snapshot, not a continuing connection to the source. Arbitrary CMS/API responses need conversion to the Delight schema first.

The configuration is validated before writing, including URL safety and text contrast. Existing files are never overwritten, including the input file. Press Ctrl+C to cancel. Invalid input stops with an error; rerun with corrected values. Setup does not deploy, upload data or connect a chat account. Remote requests have a 15-second deadline and a 256 KiB limit; embedded URL credentials are rejected. Redirects are not followed: use the final public HTTPS JSON URL. Use only data intended to be public.

For an agent, build script or CI job, pass `--yes` to avoid questions:

```sh
node cli.mjs setup --yes --source catalog.json --name "My website" --accent '#147d70' --output delight.config.json
node cli.mjs doctor --config delight.config.json --json
```

| Setup option | Default / meaning |
| --- | --- |
| `--source FILE_OR_HTTPS_URL` | Blank means fictional starter data. A supplied source must already use the Delight schema. |
| `--name NAME` | Imported profile name, or `My website`; also sets the gallery title. |
| `--accent`, `--background`, `--text` | Six-digit hex colors, quoted in shell commands; defaults come from the source or starter. |
| `--output FILE` | New `delight.config.json` in the current directory. Its parent directory must exist. |
| `--yes` | Use the supplied values and defaults without a terminal; required for unattended execution. |

To check a running instance, start `node cli.mjs --config delight.config.json` in another terminal, then:

```sh
node cli.mjs doctor --config delight.config.json --endpoint http://127.0.0.1:3001/mcp --json
```

Omit `--json` for readable text. The JSON output is one object with `schemaVersion: 1`, package `version`, `ok` and `checks`. Each check has `id`, `status`, `message` and an optional `fix`. Statuses are `pass`, `fail`, `warn` or `manual`. Exit 1 means at least one failure; exit 0 means no failures, and can still include warnings or required manual checks. Unknown or repeated options fail rather than being ignored.

`doctor` checks Node.js, the configuration, shipped gallery/embed/demo/schema assets and HTTP bind settings. It does not check whether a port is free. An optional endpoint check uses the actual MCP client with a 10-second overall deadline: it verifies the four read-only tools, retrieves the Apps HTML resource and, when `--config` is provided, compares the profile name and first entry's name and summary. This is a useful connection check, not a complete catalog equality test.

Use HTTPS for remote endpoints; HTTP is allowed only on localhost. URLs with credentials, query parameters or fragments are rejected. Redirects are not followed; use the endpoint's final URL. The diagnostic does not sign in to a protected server. If the configuration is invalid, no endpoint request is made. Without `--config`, the report warns that the server would use the Full Iron reference catalog. Without `--endpoint`, no server is contacted.

Browser WebMCP support and actual MCP Apps rendering remain `manual` checks, even when all protocol checks pass. Open your website in the intended browser and test a distinctive entry through its discovered tools. Then connect the same catalog to the intended chat host and check that its gallery renders. A remote chat host needs a public HTTPS deployment; it cannot reach your localhost.

## Add to a static website

```sh
npx delight-mcp@0.2.0 --export-site public-agent --config delight.config.json
```

Upload the new directory to your host. It contains `index.html`, `embed.js` and `delight.config.json`. Existing directories are not overwritten. Alternatively, host the module and JSON under `/agent` on an existing site and add:

```html
<div data-delight-gallery></div>
<script type="module" src="/agent/embed.js" data-delight-config="/agent/delight.config.json"></script>
```

Adjust both URLs to your upload path. Use HTTP(S), not `file://`. WebMCP tools register on the page when the browser supports the API. The gallery works without WebMCP. Omit the `div` for tools without a gallery. Use one catalog per document.

Your platform must allow custom JavaScript. A Content Security Policy restricting inline scripts also applies to the gallery's sandboxed `srcdoc` frame; configure the host policy accordingly or serve the gallery on a dedicated page. Browser requests to another origin require CORS. Everything in the JSON is public: keep credentials and private records on your backend.

## Configure data and appearance

| JSON field | Content |
| --- | --- |
| `schemaVersion` | `1` |
| `$schema` | Optional editor schema reference; not fetched by Delight |
| `locale` | BCP 47 language tag; defaults to `en` |
| `profile` | `name`, `focus`, `bio`; optional `highlights` and `sourceLinks` |
| `projects` | Up to 200 entries: unique `id`, `name`, `summary`; optional `description`, `kicker`, `tags`, `proof`, `limitations`, `sourceLinks` |
| `contacts` | `channel` and `url` pairs |
| `appearance` | `title`, `subtitle`, `accent`, `background`, `text` |

Each source link contains `label` and `url`. Use HTTPS or mailto URLs without embedded credentials. IDs contain 1–80 lowercase letters, digits or hyphens and begin with a letter or digit. Colors are six-digit hex values. Text and background must meet 4.5:1 contrast. The JSON file must fit within 256 KiB. Unknown fields are rejected to catch misspellings.

The stable tool names `search_portfolio` and `get_project` also work for products, services or documentation represented as entries in `projects`. Query `*` browses entries. `limit` is 1–6 (default 6). A catalog has one configured language; content is not automatically translated. Export a different catalog for another language. Gallery controls currently use English; catalog text is marked with its configured language for assistive technology.

In 0.2, update the published JSON and reload the page; restart the MCP process after editing its file. The 0.3 preview adds mapped JSON API sources and automatic refresh. See the [CMS/API guide](https://full-iron.com/delight-mcp/sources.md), also included as `docs/sources.md`. Source settings and optional bearer-token environment references stay separate from the public catalog. Direct database queries, arbitrary code and HTML scraping are outside this adapter.

## Integrate with an existing frontend

```ts
import { loadDelightConfig, mountDelight } from 'delight-mcp/site'

const config = await loadDelightConfig('/delight.config.json')
const handle = await mountDelight({
  config,
  target: document.getElementById('catalog')!,
})
// On unmount:
handle.destroy()
```

Call on the client after mounting the target element. `mountDelight` resolves after the gallery initializes, or rejects if initialization fails. `handle.registered` reports WebMCP registration; gallery support is independent. `destroy()` removes the frame and registrations. An optional AbortSignal also ends this lifecycle. Call `destroy()` before mounting another catalog in the same document.

`loadDelightConfig` revalidates the browser cache and bounds the complete request, including the response body, to 15 seconds and 256 KiB. Caller cancellation is preserved. The gallery handshake has a separate 15-second timeout. Catch errors in frontend integrations; the automatic HTML embed shows a readable failure message and logs the underlying cause in the browser console.

For tools without the gallery:

```ts
import { parseDelightConfig, registerConfiguredWebTools } from 'delight-mcp/webmcp'
import type { PortfolioModelContext } from 'delight-mcp/webmcp'
const controller = new AbortController()
const context = (document as Document & { modelContext?: PortfolioModelContext }).modelContext
await registerConfiguredWebTools(context, controller.signal, parseDelightConfig(yourData))
// On teardown:
controller.abort()
```

`createCatalog(config)` exposes the same tool definitions, calls, results and link validation for custom hosts. The legacy `registerPortfolioWebTools` function registers the reference catalog.

## Connect MCP clients and Apps

For clients using `mcpServers` JSON:

```json
{"mcpServers":{"delight":{"command":"npx","args":["-y","delight-mcp@0.2.0","--stdio","--config","/absolute/path/delight.config.json"]}}}
```

Use your client's configuration format. Some Windows clients require `npx.cmd`. Cloud clients need a public HTTPS `/mcp` endpoint; a static export does not create one.

For custom Node.js hosting:

```ts
import { createServer, parseDelightConfig } from 'delight-mcp/server'
const server = createServer({ config: parseDelightConfig(yourData) })
// Connect server to your MCP SDK transport.
```

Copy `node_modules/delight-mcp/examples/vercel` into a separate deployment project, replace its `delight.config.json`, install dependencies and deploy to your Vercel account. Add any custom domain explicitly to the host and origin allowlists. The server reads only public data and provides no authentication.

Search and entry-detail tools attach the `ui://delight/catalog` Apps resource. A supporting host displays the same branded gallery; other clients receive structured results and source links. Installing the package does not automatically connect ChatGPT or Codex.

## Verify the integration

1. Validate the JSON with `--check-config`.
2. Run the configured CLI; search for a distinctive word from your data.
3. Confirm the returned IDs, links and gallery colors belong to your catalog.
4. Deploy the static export over HTTPS and check the gallery in an ordinary browser.
5. On a WebMCP browser, discover the four tools and call `get_project` with a returned ID.
6. Connect your MCP host and repeat the query. Confirm the Apps card if that host supports Apps.

## Troubleshoot installation

| Symptom | Check |
| --- | --- |
| No gallery and no tools | The page must allow custom JavaScript. Serve `embed.js` as JavaScript over HTTP(S), not `file://`. Check both URLs in the script tag. |
| The catalog could not load | Check the browser console for the underlying error. The JSON request must return valid UTF-8 JSON with a successful HTTP status. Validate the file with `--check-config`. |
| A request times out | The JSON endpoint must finish within 15 seconds. Check the host, redirects and network; a small static JSON file is sufficient. |
| Gallery initialization times out | Inspect Content Security Policy errors. The bundled gallery uses inline scripts/styles in a sandboxed frame. Use a dedicated page with a policy that explicitly supports the gallery; retain your site's other protections. |
| Same-origin data works, another domain fails | That JSON endpoint must allow your site's origin through CORS. Browser fetch cannot bypass the endpoint's policy. |
| Gallery works but no WebMCP tools appear | Check browser support for `document.modelContext`, registration errors and existing tool names. The ordinary gallery remains usable without WebMCP. |
| A cross-origin iframe has no browser tools | The embedding site controls the `tools` Permissions Policy. Prefer placing the script directly in the page you own; cross-origin discovery requires explicit host cooperation. |
| Duplicate tools after navigation | Keep one instance per document and call `destroy()` or abort its signal during frontend teardown. |
| MCP shows the Full Iron catalog | Pass `--config` with the intended file, using an absolute path in an assistant's configuration. Static JSON changes do not automatically update a separate MCP server. |
| MCP tools work but no Apps card appears | Confirm the client supports MCP Apps. Use structured tool results in clients without an Apps renderer. |

For agent-driven setup, completion means a distinctive entry from the supplied catalog is returned through both browser and MCP tools. Preserve returned IDs and source links; do not treat an empty search as an installation failure. Diagnose against discovered tool schemas and the actual configured locale.

[Documentation](https://full-iron.com/docs/delight-mcp) · [Reference demo](https://full-iron.com/portfolio-agent) · [npm](https://www.npmjs.com/package/delight-mcp)
