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

1. Clone this repository

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

2. Install dependencies

npm install

3. 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.

4. 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:

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

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

4. Check for errors in the console output
5. 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

1. Edit server.js to modify guidelines
2. Restart Cursor Desktop to reload changes
3. 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

• MCP Documentation
• Cursor Documentation
• Design System Guidelines

Contributing

We welcome contributions! To add or improve guidelines:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/new-component)
3. Add or update component guidelines in server.js
4. Test with Cursor Desktop
5. 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