# Uidx

> A Visual Design that ships with your code. Agents and humans work together on the same canvas, where every change is a diffable JSX stored in a .uidx file inside your repo. Built on OpenPencil and Skia, with MCP built in.

- **Type:** MCP server
- **Install:** `agentstack add mcp-uidxkit-uidx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [uidxkit](https://agentstack.voostack.com/s/uidxkit)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [uidxkit](https://github.com/uidxkit)
- **Source:** https://github.com/uidxkit/uidx

## Install

```sh
agentstack add mcp-uidxkit-uidx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Design in your repo.
A visual design workspace for your project.Editable on a canvas. Readable by people and agents. Versioned with your code.

  
  
  

*Workflow illustration: one design, shared by the canvas, your files, and your tools.*

## What is UIDX?

UIDX brings a design canvas into your application's repository. Install
`@uidxkit/uidx` as a **local development dependency**, run `npm run uidx`, and
work on designs stored in your project's `.uidx/` folder.

A `.uidx` file combines Markdown describing a design's purpose with a declarative
node tree describing its appearance. Edit the canvas and the file updates. Edit
the file and the canvas follows. Changes produce focused text diffs you can
review in a pull request.

- **A visual workspace.** Create pages, draw shapes, edit text, and adjust layout
  and styling from the canvas and inspector.
- **Reusable design systems.** Components, instances, variants, slots, and design
  tokens share a document namespace.
- **Your project owns the files.** Keep designs, assets, and fonts next to your
  application and version them with Git.
- **A shared workflow for people and agents.** The CLI and MCP bridge let external
  tools inspect and edit the same files the viewer uses.
- **Local by default.** The viewer and project server run on your machine. Canvas
  synchronization does not require an LLM or a hosted design service.

UIDX is an early release. The file format and APIs may change
before 1.0. It is a design workspace; it does not render your application's
existing UI components as Storybook stories.

## Install

Requires **Node.js 22.19 or newer**. Node 24 is recommended.

Run these commands **inside your application's repository**:

```sh
npm install --save-dev @uidxkit/uidx
npm run uidx
```

Installation adds the `uidx` and `uidx:mcp` scripts and creates `.uidx/` when it
doesn't exist. Existing scripts, configuration, and designs are preserved.
The CLI, server, viewer, WASM, and bundled fonts live in your project's
`node_modules`; a global UIDX installation is not required.

If npm install scripts are disabled, initialize once with
`npx --no-install uidx init`. If your project already uses a script named `uidx`,
choose another with `npx --no-install uidx init --script design`, then run
`npm run design`.

## Your design workspace

```text
your-project/
├── package.json          # @uidxkit/uidx devDependency and npm scripts
├── .mcp.json             # connection for MCP clients
├── src/
└── .uidx/
    ├── config.json       # project settings
    ├── uidx.json         # document name, page patterns, and asset patterns
    ├── welcome.uidx      # initial page for a new workspace
    ├── assets/
    └── fonts/
```

Open the viewer, click **New page**, give it a name, and start designing. New
pages are saved in your design folder and appear in the overview. Commit your
project's `.uidx/` files alongside application code.

### Configuration

Set the shared viewer and MCP port in `.uidx/config.json`:

```json
{
  "port": 4400
}
```

Restart `npm run uidx` after changing it. Use `npm run uidx -- --port 4500` for a
one-time override. If the requested port is busy, UIDX tries the next available
one and reports its actual address. Configuration currently uses JSON.

The separate `.uidx/uidx.json` manifest controls which files belong to the document:

```json
{
  "id": "my-project",
  "files": ["**/*.uidx"],
  "assets": ["assets/**"]
}
```

### CLI and MCP

`npm run uidx` starts the local viewer, file synchronization server, and MCP HTTP
endpoint on one port. MCP clients use the generated `.mcp.json` to launch
`npm run --silent uidx:mcp`, a stdio bridge to that running project server.

```sh
npx --no-install uidx status
npx --no-install uidx check
npx --no-install uidx fmt --check
```

The CLI also supports reading, creating, editing, and rendering pages. See the
[CLI guide](packages/cli/README.md) and [agent architecture](packages/agent/README.md).

## Documentation

- [Drawing icons and custom graphics](docs/graphics-tools.md)
- [Fonts](docs/fonts.md)
- [Property vocabulary](docs/property-vocabulary.md)
- [Architecture decisions](docs/decisions)
- [Release guide](docs/releasing.md)
- [Changelog](CHANGELOG.md)

## Contributing and license

Bug reports, documentation improvements, and pull requests are welcome.
See [Contributing](CONTRIBUTING.md) for development setup and checks.
Follow the [Code of Conduct](CODE_OF_CONDUCT.md) and report vulnerabilities through
the [security policy](SECURITY.md). Changes to `main` are merged by the owner.

UIDX is [MIT licensed](LICENSE). Third-party code and fonts retain their
[respective licenses](THIRD_PARTY_NOTICES.md).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [uidxkit](https://github.com/uidxkit)
- **Source:** [uidxkit/uidx](https://github.com/uidxkit/uidx)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-uidxkit-uidx
- Seller: https://agentstack.voostack.com/s/uidxkit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.