Muibook Guidelines MCP Server

An MCP (Model Context Protocol) server that provides design system guidelines and component documentation to Cursor Desktop.

Overview

This MCP server delivers comprehensive design system guidelines directly to Cursor, enabling it to provide accurate, consistent advice about UI components, patterns, and best practices from your design system.

Features

Component Guidelines: Detailed documentation for UI components (buttons, forms, navigation, etc.)
Visual References: Direct links to component anatomy diagrams and examples
Accessibility Standards: Built-in accessibility requirements and best practices
Design Tokens: Access to color, typography, spacing, and other design tokens
Usage Patterns: Real-world examples and usage guidelines

Installation

Prerequisites

Node.js (v16 or higher)
Cursor Desktop application

Setup

Clone this repository

git clone https://github.com/your-org/muibook-guidelines-mcp.git
cd muibook-guidelines-mcp

Install dependencies

npm install

Configure Cursor Desktop

Edit your Cursor Desktop config file:

macOS: ~/Library/Application Support/Cursor/mcp_config.json
Windows: %APPDATA%\Cursor\mcp_config.json

Add this server:

{
  "mcpServers": {
    "muibook-guidelines": {
      "command": "node",
      "args": ["/absolute/path/to/muibook-guidelines-mcp/server.js"]
    }
  }
}

Replace /absolute/path/to/muibook-guidelines-mcp/ with the actual path where you cloned this repository.

Restart Cursor Desktop

Completely quit and reopen Cursor Desktop to load the MCP server.

Usage

Once installed, you can ask Cursor about design guidelines:

Examples:

"Show me the button component guidelines"
"What are the accessibility requirements for buttons?"
"What button variants are available?"
"How should I use primary vs secondary buttons?"

Available Prompts

serve_guidelines - Returns comprehensive design system guidelines including component anatomy, usage patterns, accessibility requirements, and visual references.

What's Included

Button Component Guidelines

Complete anatomy breakdown with visual diagrams
Usage guidelines and best practices
Five button variants (Primary, Secondary, Tertiary, Link, Icon)
Accessibility requirements
Component states and behaviors

Full documentation: https://guides.muibook.com/button

Troubleshooting

Red indicator in Cursor Desktop

The server isn't connecting. Try these steps:

Verify the path in your config file is correct and absolute
Check Node.js version: Run node --version (needs v16+)

Test the server manually:

cd /path/to/muibook-guidelines-mcp
node server.js

Check for errors in the console output
Restart Cursor completely (quit and reopen)

Guidelines not appearing

Confirm the server shows as connected in Cursor (not red)
Try asking explicitly: "Show me the serve_guidelines prompt"
Check Cursor's MCP logs for errors

Images not loading

Ensure you have internet connectivity (images are hosted externally)
Check that the URLs in the guidelines are accessible
Try fetching an image URL directly in your browser

Development

Running the server locally

node server.js

Making changes

Edit server.js to modify guidelines
Restart Cursor Desktop to reload changes
Test your prompts

Adding new components

Edit the prompt content in server.js:

if (request.params.name === "serve_guidelines") {
  return {
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `# Add your new component guidelines here`,
        },
      },
    ],
  };
}

Project Structure

muibook-guidelines-mcp/
├── server.js            # MCP server implementation
├── package.json         # Dependencies and metadata
└── README.md           # This file

Resources

Contributing

We welcome contributions! To add or improve guidelines:

Fork this repository
Create a feature branch (git checkout -b feature/new-component)
Add or update component guidelines in server.js
Test with Cursor Desktop
Submit a pull request

License

[Your License Here]

Support

For issues or questions:

Open an issue on GitHub
Check the troubleshooting section above
Contact the design system team

NPM Package

Versioning

Follow semantic versioning: major.minor.patch
- Patch: bug fixes, no API changes
- Minor: new features, backward-compatible
- Major: breaking changes, API changes
Keep package.json and server.json versions synchronized.

Bumping Versions

Patch:

npm version patch

Minor:

npm version minor

Major:

npm version major

This updates package.json version and creates a Git tag automatically.

Publishing to NPM

Option A – Direct publish (NPM will prompt for credentials if needed):

npm publish --access public

Option B – Pre-login (recommended for repeated releases):

npm login
npm publish --access public

--access public ensures the package is publicly available.
Make sure package.json includes the MCP identifier:

"mcpName": "io.github.YOURUSERNAME/muibook-guidelines-mcp"

⸻

Optional MCP Registry Update

Ensure server.json matches the current version:

"version": "1.0.0"

Publish to MCP Registry:

mcp-publisher publish

⸻

GitHub Release (Optional)

Tag the release:

git tag v1.0.0
git push origin v1.0.0

Add release notes in GitHub for tracking changes.

⸻

Local Development & Testing

Install dependencies:

npm install

Run locally:

npm start

Connect via MCP client (Cursor, Cline, etc.) or mcp.json:

{
  "servers": {
    "muibook-guidelines-mcp": {
      "command": "node",
      "args": ["./node_modules/muibook-guidelines-mcp/server.js"]
    }
  }
}

Release Checklist

• Test MCP server locally • Update package.json and server.json versions • Bump version (patch, minor, or major) • Commit and push changes • Publish to NPM (--access public) • Optionally publish to MCP Registry (mcp-publisher publish) • Optionally create GitHub release with notes

References

• NPM Publishing Docs • MCP Registry Docs • Semantic Versioning

MCP Servers