Base Ui Mcp

Table of Contents

1. Getting Started
   • Installation
2. Usage
3. Roadmap
4. Contributing
5. License
6. Contact
7. Acknowledgments

Getting Started

To use Base UI in an application, install the package and import its stylesheet. To work on the library itself, clone the repository and run Storybook.

Installation

To use the library in an application:

1. Install the package

   npm install @gamecrafters/base-ui
   

2. Import the stylesheet once, at the root of the application

   import '@gamecrafters/base-ui/main.css';
   

To work on the library itself:

1. Clone the repo

   git clone https://github.com/gamecrafters-io/base-ui.git
   

2. Install NPM packages

   npm install
   

3. Start the docs and the site, where the components are developed and read

   npm run dev
   

4. Install the browsers the end to end suites are driven through, which is only needed once

   npx playwright install chromium
   

5. Working from a fork, change the git remote url to avoid accidental pushes to the base project

   git remote set-url origin https://github.com/your_username/base-ui.git
   git remote -v # confirm the changes
   

(back to top)

Usage

Wrap the application in a ThemeProvider so the tokens resolve, then reach for the components:

import { Box, Button, FormControl, Stack, TextInput, ThemeProvider } from '@gamecrafters/base-ui/react';
import '@gamecrafters/base-ui/main.css';

const App = () => (
  <ThemeProvider colorMode="auto">
    <Box padding="normal" background="muted" border="default" radius="medium">
      <Stack gap="normal">
        <FormControl required>
          <FormControl.Label>Name</FormControl.Label>
          <TextInput block />
          <FormControl.Caption>The name people will know you by</FormControl.Caption>
        </FormControl>
        <Button variant="primary">Save</Button>
      </Stack>
    </Box>
  </ThemeProvider>
);

export default App;

colorMode takes day, night or auto; auto follows the operating system. A nested ThemeProvider only has to say what it changes, so a subtree can hold a scheme of its own.

For a right-to-left subtree, wrap it in a DirectionProvider:

import { DirectionProvider } from '@gamecrafters/base-ui/react';

<DirectionProvider direction="rtl">{children}</DirectionProvider>;

The scripts are run from the root and reach the packages through Turbo, which caches a task against its inputs so an unchanged package is not built or tested twice:

Script	What it does
npm run dev	Runs the docs and the site, on ports 3001 and 3000
npm test	Runs the Vitest suites
npm run test:e2e	Runs the Playwright suites against Storybook
npm run build	Builds the package with Rolldown into packages/react/build/
npm run build:docs	Builds the static Storybook into apps/docs/storybook-static/
npm run build:web	Builds the site into apps/web/build/
npm run lint	Lints each package's own sources with ESLint
npm run format	Applies both the ESLint and Prettier fixes
npm run clean	Removes the build output

Any one of them can be pointed at a single package instead, with npm run build --workspace @gamecrafters/base-ui.

Every component has a page in Storybook, with a Playground story for its props and a Features section for what it can do.

The MCP server

The workspace also holds @gamecrafters/base-ui-mcp, a Model Context Protocol server that lets a coding agent ask the design system what it holds rather than guess at it. Everything it answers is read out of the library's own sources at the end of a build, so it says what the components were written as rather than what was once written about them.

{
  "mcpServers": {
    "base-ui": {
      "command": "npx",
      "args": ["-y", "@gamecrafters/base-ui-mcp"]
    }
  }
}

Tool	What it answers
get_setup_guide	What an application does once, before any component is written into it
list_components	Every component and provider the package exports
get_component	Every prop one of them takes, with what it is for and the values it takes
get_component_examples	The same component as it is already written, taken from its stories
list_tokens	The design tokens to reach for in place of a literal colour or measurement

Working on the server itself, npm run build --workspace @gamecrafters/base-ui-mcp writes it and its registry to packages/mcp/build/, which a client can be pointed straight at with node.

(back to top)

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Run npm run lint, npm test and npm run test:e2e
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

A new component follows the shape of the ones already there: a ComponentName.tsx, a ComponentName.types.ts, an index.ts, a Vitest suite and two Storybook files under packages/react/src/components/<component-name>, with its stylesheet under packages/react/src/styles/components and one line added to each of the two barrels.

A Vitest suite is where a component is held to what it draws and what it says, and it is what every component carries. A Playwright suite under e2e is for the behaviour only a browser can settle — where focus lands, what the top layer holds, what colour the cascade came out with — and is added where a component has some.

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

LinkedIn   Discord   Twitter   YouTube  

(back to top)

Acknowledgments

(back to top)