# Catalog Discovery — Tools and Resources

> For AI: how to discover Dynamic UI components, hooks and official patterns through this MCP, and which source to use for each question. Everything except `widgets-list-patterns` is pinned to the Dynamic UI version the MCP is validated against.

---

## Sources

| Source | What it returns | Pinned |
|--------|-----------------|--------|
| `widgets-list-components` (Tool) | Every catalog entry: components, then context providers, then hooks, each with `name`, `description`, `propsCount` (for hooks, the number of parameters) and `section` (`components`, `contexts`, `hooks`). No parameters | Yes (`api.json`) |
| `widgets-get-component-props` (Tool) | One full `api.json` entry, as published: props, `types`, `forwardedProps`, `parent` and `accessor` for components; parameters, returns and `returnType` for hooks. Adds `name` (as requested), `key` (the entry's name in the catalog) and `section` | Yes (`api.json`) |
| `modyo://widgets/catalog/components` (Resource) | Lightweight list of Storybook components: `id`, `name`, `key` (equals `id`), `description`, `storyCount`, plus `dynamicUiVersion` | Yes (Storybook manifest) |
| `modyo://widgets/catalog/components/{componentId}` (Resource) | The full Storybook entry: stories with snippet code, props with types, JSDoc tags | Yes |
| `modyo://widgets/catalog/patterns` (Resource) | Official patterns: pattern components (`pattern-component`) and their stories (`pattern-story`), plus MDX pattern docs (`source: mdx`) only when the pinned version publishes them. Each entry has `id`, `title` (the display field common to all) and `source`; `name` only on stories and MDX docs | Yes |
| `modyo://widgets/catalog/patterns/{patternId}` (Resource) | The full content of one pattern | Yes |
| `widgets-list-patterns` (Tool) | Pattern ids, titles and names from the **live** Storybook index | No: it reads the latest published index, so its ids can differ from the Resources |

---

## Which one to use

| Question | Use |
|----------|-----|
| Which components, contexts or hooks exist? | `widgets-list-components` |
| What exactly does `DButton` (or `DCard.Body`, `DContextProvider`, `useDToast`) accept? | `widgets-get-component-props` with that name |
| Is there an official pattern for this screen? | `modyo://widgets/catalog/patterns`, then `…/patterns/{patternId}` |
| I need a working snippet of a component | `modyo://widgets/catalog/components/{componentId}` |

---

## Names and ids

- **Tools take component names.** `widgets-get-component-props` accepts `DButton`, a subcomponent by its own name or by its accessor (`DCardBody` or `DCard.Body`), `DContextProvider`, or a hook (`useDToast`). Names are case-sensitive. When a name is not found, the error lists the available names by section.
- **Catalog Resources take Storybook ids**, not component names: `modyo://widgets/catalog/components/design-system-components-alert`, not `…/DAlert`. Read the ids from `modyo://widgets/catalog/components` (the `key` field). With an unknown id, the error says so and shows the first available ids.
- **Pattern ids** come from `modyo://widgets/catalog/patterns`. The detail resource accepts a pattern component id (`patterns-list-group`) or a pattern story id (`patterns-list-group--transaction-history`).

---

## Workflow before writing UI

1. Read `modyo://widgets/catalog/patterns` and look for a pattern that matches the request.
2. If one matches, read it with `modyo://widgets/catalog/patterns/{patternId}` and use it as the base.
3. Pick the remaining components from `modyo://docs/widgets/components-_index`.
4. Confirm each component's contract with `widgets-get-component-props`.

---

## Errors

| Situation | What happens |
|-----------|--------------|
| A catalog manifest is not published for the pinned version (HTTP 403 or 404) | The Resource fails with a message saying the catalog for that Dynamic UI version is not published, and asks to check the compatibility matrix |
| Unknown component id in `…/components/{componentId}` | The error reminds that the parameter is the Storybook id, not the React name, and lists available ids |
| Unknown pattern id | The error lists where it looked and points to `modyo://widgets/catalog/patterns` |
| Unknown name in `widgets-get-component-props` | The error lists the available names grouped by section and suggests `widgets-list-components` |

---

## See also

- `modyo://docs/widgets/components-_index` — components by purpose and the rules shared by all of them
- `modyo://docs/widgets/INDEX` — Pattern Discovery
