# Using Neo with coding agents

Neo does not require a package manager or registry. Its agent interface combines a small, optional Agent Skill with stable, inspectable resources. The MCP transport is available at `https://mcp.neo.voorhees.dev/mcp`; the static catalog remains the portable fallback and source record.

## Agent Skill setup

Install the complete Neo skill into the current project:

```sh
mkdir -p .agents/skills && \
neo_skill_tmp="$(mktemp -d)" && \
curl -fsSL https://neo.voorhees.dev/skill/neo-skill.zip -o "$neo_skill_tmp/neo-skill.zip" && \
unzip -oq "$neo_skill_tmp/neo-skill.zip" -d .agents/skills
```

This creates `.agents/skills/neo`. Keeping it in the project lets a team version the same adoption workflow with its code. Install to `$HOME/.agents/skills` instead when you want the skill available to your local agent across projects.

The package contains:

- `SKILL.md`, the repeatable process for discovering, copying, adapting, and verifying Neo components.
- `references/targets.md`, the rules for choosing canonical Web source, React, or another framework adapter.
- `agents/openai.yaml`, presentation metadata plus the dependency on Neo's Streamable HTTP MCP endpoint.

The skill and MCP serve different jobs. The skill teaches an agent the stable workflow; MCP supplies the live catalog and current source. Adding a component to the published Neo catalog therefore does not require repackaging the skill. Update the skill package only when the workflow or integration metadata changes.

## Copyable starter prompt

Use this once at the start of an agent task. Component manifests remain factual and do not contain per-component prompts.

```text
Use Neo for this interface.

1. Use the Neo MCP server at https://mcp.neo.voorhees.dev/mcp when it is available in this environment. Otherwise read https://neo.voorhees.dev/llms.txt and https://neo.voorhees.dev/neo/catalog.json.
2. Inspect this project's stack and existing component conventions.
3. Add only the Neo components the interface needs. Use Web source as the reference; use the maintained React adapter in React projects.
4. Copy the shared Neo stylesheet once, then copy component source from each manifest.
5. Preserve the manifest contract, accessible semantics, keyboard behavior, dark/light themes, and 44px touch targets.
6. Keep the copied source local and adapt it to the project without introducing a Neo runtime or registry.
```

The explorer's **Install Neo** panel provides the skill installer, MCP setup, and small Web and React starter commands. The prompt remains a portable fallback for agents without skill support. Individual component pages provide the exact source command for that component.

## Recommended workflow

1. With MCP, call `list_components` and select a component. Without MCP, read `/neo/catalog.json`.
2. Call `get_foundations` once for shared CSS and tokens, then `get_component` for each selected component. Without MCP, read that component's manifest from `/neo/components/{name}.json`.
3. Inspect the consuming project's stack and existing conventions.
4. Use the canonical `web` files for HTML/CSS/JS work or when no maintained adapter exists.
5. Use the `react` files when the project is React and preserving the adapter is preferable to translating the Web source.
6. Copy the shared stylesheet once, then copy only the selected component files. The starter set contains Glass surface, Button, and Text field.
7. Preserve the manifest's `contract` while adapting names, imports, or framework state.
8. Verify keyboard behavior, labels, focus, dark and light themes, reduced motion, and mobile layout.

## MCP setup

Neo is a public, read-only Streamable HTTP server. It does not require a token. Connect once at:

```text
https://mcp.neo.voorhees.dev/mcp
```

### Codex CLI, desktop, and IDE extension

```sh
codex mcp add neo --url https://mcp.neo.voorhees.dev/mcp
```

Codex desktop can also add it through **Settings → MCP servers → Add server**. Choose **Streamable HTTP**, name it `neo`, enter the URL above, save, and restart. Codex CLI, desktop, and the IDE extension share the same MCP configuration.

### Claude Code

```sh
claude mcp add --transport http --scope user neo https://mcp.neo.voorhees.dev/mcp
```

Use `--scope project` instead when the connection should be committed for a team rather than available to the current user across projects.

### Cursor

Add this to `~/.cursor/mcp.json` for global use, or `.cursor/mcp.json` in one project:

```json
{
  "mcpServers": {
    "neo": {
      "url": "https://mcp.neo.voorhees.dev/mcp"
    }
  }
}
```

### Other MCP clients

Create a remote server named `neo`, select **Streamable HTTP**, and use the endpoint above. Authentication and custom headers should be left empty.

After connecting, verify that the client discovers these tools:

- `list_components` searches the live catalog and returns current component names, groups, descriptions, and manifests.
- `get_component` returns one component's behavior contract and complete Web or React source files.
- `get_foundations` returns Neo's shared stylesheet, tokens, agent guide, and optional Skill reference.

The server reads the catalog on each tool call rather than shipping a fixed component list. Publishing a new component to the Neo catalog therefore makes it discoverable without rebuilding the MCP service.

## Why Web is canonical

Semantic HTML and browser behavior are the smallest common contract across frontend frameworks. An agent can translate that source to Vue, Svelte, Web Components, server-rendered templates, or a one-file page without first reversing React abstractions.

React remains a maintained adapter because controlled state, refs, and keyboard interactions should not be regenerated for every use. Other verified adapters can be added later without changing the design system's foundation.

## What each agent-facing file does

- `/llms.txt` helps an agent discover the useful documentation and catalog.
- `https://mcp.neo.voorhees.dev/mcp` exposes the same evolving library through MCP for clients that support tool-based discovery.
- `/neo/catalog.json` is the component index.
- `/neo/components/{name}.json` is the authoritative file and behavior contract for one component.
- `/skill/neo-skill.zip` installs the complete optional workflow; `/skill/neo/SKILL.md` remains readable as a raw file.
- `AGENTS.md` belongs in the consuming repository and records local conventions after Neo is adopted. It is not a download mechanism.

## Why there is no required shadcn registry

A shadcn registry is a capable transport for source files, especially in projects already using the shadcn CLI. It is not necessary for Neo's framework-neutral model and it does not itself make a library agent-first. Neo can offer a registry compatibility adapter later without making that schema or CLI the source of truth.