Visa Design System MCP Server
Provides access to Visa's Product Design System resources, including design tokens, component specifications, and usage guidelines for consistent UI development.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Visa Design System MCP Server show me the design tokens for buttons"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Visa Design System MCP Server
A Model Context Protocol (MCP) server that provides AI tools with access to Visa's Product Design System resources, including design tokens, component specifications, and usage guidelines.
Table of Contents
Related MCP server: WordPress Design System MCP Server
Installation
Prerequisites
Node.js 18+
npm or yarn package manager
Install from Source
# Clone the repository
git clone <repository-url>
cd visa-design-system-mcp
# Install dependencies
npm install
# Build the project
npm run buildInstall as Global Package
# Install globally (after building)
npm install -g .
# Or link for development
npm linkQuick Start
1. Start the Server
# Start with default configuration
npm start
# Or use the CLI with custom options
npx visa-design-system-mcp start --data-path ./custom-data --log-level debug2. Test the Server
# Test server functionality
npm test
# Run integration tests
npm run test:integration3. Connect an MCP Client
See MCP Client Setup for detailed configuration instructions.
Configuration
Environment Variables
The server can be configured using environment variables:
Variable | Description | Default | Example |
| Path to design system data files |
|
|
| Logging level |
|
|
| Enable automatic data reloading |
|
|
| Cache time-to-live in seconds |
|
|
| Maximum concurrent requests |
|
|
Configuration File
Create a config.json file in the project root:
{
"dataPath": "./data",
"logLevel": "info",
"enableFileWatching": true,
"cacheTTL": 300,
"maxConcurrentRequests": 100,
"server": {
"name": "visa-design-system-mcp",
"version": "1.0.0"
}
}CLI Options
npx visa-design-system-mcp start [options]
Options:
--data-path <path> Path to design system data files (default: "./data")
--log-level <level> Logging level: debug, info, warn, error (default: "info")
--config <file> Path to configuration file
--no-file-watching Disable automatic file watching
--verbose Enable verbose logging
--help Display help informationUsage
Basic Server Operations
# Start the server
npm start
# Start with custom data path
MCP_DATA_PATH=/custom/path npm start
# Start with debug logging
MCP_LOG_LEVEL=debug npm start
# Start without file watching (for production)
MCP_ENABLE_FILE_WATCHING=false npm startAvailable MCP Tools
The server exposes the following MCP tools:
Design Token Tools
get-design-tokens- Retrieve design tokens with optional filteringsearch-design-tokens- Search tokens by name or valueget-design-token-details- Get detailed token informationget-design-token-categories- List all token categories
Component Tools
get-components- List all components with optional filteringget-component-details- Get detailed component specificationsget-component-examples- Retrieve component code examplessearch-components- Search components by name or description
Guidelines Tools
get-guidelines- Retrieve design guidelines with optional filteringget-guideline-details- Get detailed guideline informationsearch-guidelines- Search guidelines by content or tags
For detailed API documentation, see API.md.
MCP Client Setup
Claude Desktop
Add the following to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"visa-design-system": {
"command": "node",
"args": ["/path/to/visa-design-system-mcp/dist/index.js"],
"env": {
"MCP_DATA_PATH": "/path/to/data",
"MCP_LOG_LEVEL": "info"
}
}
}
}Custom MCP Client
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({
command: 'node',
args: ['/path/to/visa-design-system-mcp/dist/index.js']
});
const client = new Client({
name: "my-app",
version: "1.0.0"
}, {
capabilities: {}
});
await client.connect(transport);
// List available tools
const tools = await client.request({
method: "tools/list"
}, {});
console.log('Available tools:', tools.tools.map(t => t.name));Kiro IDE
Add to your .kiro/settings/mcp.json:
{
"mcpServers": {
"visa-design-system": {
"command": "node",
"args": ["/path/to/visa-design-system-mcp/dist/index.js"],
"env": {
"MCP_DATA_PATH": "/path/to/data"
},
"disabled": false,
"autoApprove": ["get-design-tokens", "get-components", "get-guidelines"]
}
}
}Development
Setup Development Environment
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode with hot reload
npm run dev
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Clean build artifacts
npm run cleanProject Structure
├── src/
│ ├── index.ts # Main server entry point
│ ├── cli.ts # Command-line interface
│ ├── mcp-server.ts # MCP protocol implementation
│ ├── config/ # Configuration management
│ ├── services/ # Business logic services
│ │ ├── design-token-service.ts
│ │ ├── component-service.ts
│ │ └── guidelines-service.ts
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ │ ├── data-manager.ts # Data loading and caching
│ │ ├── logger.ts # Logging utilities
│ │ ├── errors.ts # Error handling
│ │ └── validation.ts # Data validation
│ └── schemas/ # JSON schemas for validation
├── data/ # Design system data files
│ ├── design-tokens.json # Design token definitions
│ ├── components.json # Component specifications
│ └── guidelines.json # Design guidelines
├── tests/ # Test files
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── utils/ # Test utilities
├── dist/ # Compiled JavaScript output
└── docs/ # Additional documentationTesting
# Run all tests
npm test
# Run specific test suites
npm run test:unit # Unit tests only
npm run test:integration # Integration tests only
npm run test:performance # Performance tests
npm run test:edge-cases # Edge case tests
npm run test:mcp-compliance # MCP protocol compliance tests
# Run tests with coverage
npm run test:coverage
# Run tests for CI
npm run test:ciAdding New Features
Add new MCP tools: Implement in respective service files
Update data schemas: Modify JSON schemas in
src/schemas/Add tests: Create corresponding test files
Update documentation: Update API.md and examples
API Documentation
For comprehensive API documentation including all available tools, parameters, and response formats, see API.md.
For usage examples and integration patterns, see EXAMPLES.md.
Troubleshooting
Common Issues
Server Won't Start
Problem: Server fails to start with "Cannot find module" error
Error: Cannot find module './dist/index.js'Solution: Build the project first
npm run build
npm startProblem: Server starts but no tools are available
Error: No tools foundSolution: Check data path and file permissions
# Verify data files exist
ls -la data/
# Check file permissions
chmod 644 data/*.json
# Start with debug logging
MCP_LOG_LEVEL=debug npm startData Loading Issues
Problem: Design system data not loading
Error: Failed to load design system dataSolution: Verify data file format and location
# Validate JSON files
npm run validate-data
# Check data path configuration
echo $MCP_DATA_PATH
# Use absolute path
MCP_DATA_PATH=/absolute/path/to/data npm startProblem: File watching not working
Warning: File watching disabledSolution: Check file system permissions and enable file watching
# Enable file watching explicitly
MCP_ENABLE_FILE_WATCHING=true npm start
# Check if chokidar can access files
node -e "const chokidar = require('chokidar'); chokidar.watch('./data').on('ready', () => console.log('File watching works'));"MCP Client Connection Issues
Problem: Claude Desktop can't connect to server
Error: Failed to connect to MCP serverSolution: Check configuration and paths
{
"mcpServers": {
"visa-design-system": {
"command": "node",
"args": ["/absolute/path/to/visa-design-system-mcp/dist/index.js"]
}
}
}Problem: Tools not appearing in MCP client
Error: No tools availableSolution: Verify server initialization and tool registration
# Test server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js
# Check server logs
MCP_LOG_LEVEL=debug node dist/index.jsPerformance Issues
Problem: Slow response times
Warning: Tool call took longer than expectedSolution: Optimize caching and data loading
# Increase cache TTL
MCP_CACHE_TTL=600 npm start
# Reduce concurrent requests
MCP_MAX_CONCURRENT_REQUESTS=50 npm start
# Monitor performance
npm run test:performanceProblem: High memory usage
Warning: High memory usage detectedSolution: Optimize data structures and caching
# Monitor memory usage
node --max-old-space-size=512 dist/index.js
# Disable file watching in production
MCP_ENABLE_FILE_WATCHING=false npm startDebug Mode
Enable debug mode for detailed logging:
# Environment variable
MCP_LOG_LEVEL=debug npm start
# CLI flag
npx visa-design-system-mcp start --log-level debug --verboseDebug output includes:
Server initialization steps
Data loading progress
Tool call details
Cache operations
File watching events
Error stack traces
Log Files
Logs are written to:
Console (stdout/stderr)
Optional log file (configure via
LOG_FILEenvironment variable)
# Write logs to file
LOG_FILE=./logs/mcp-server.log npm start
# Tail logs in real-time
tail -f ./logs/mcp-server.logHealth Checks
Test server health:
# Basic connectivity test
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | node dist/index.js
# Tool availability test
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js
# Data integrity test
npm run validate-dataGetting Help
Check the logs: Enable debug logging to see detailed error information
Validate data: Run
npm run validate-datato check data file integrityTest connectivity: Use the health check commands above
Review configuration: Verify all paths and environment variables
Check permissions: Ensure the server has read access to data files
Update dependencies: Run
npm updateto get the latest versions
If you're still experiencing issues, please:
Include debug logs in your issue report
Specify your Node.js version (
node --version)Describe your MCP client setup
Provide your configuration files (with sensitive data removed)
Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Make your changes
Add tests for new functionality
Run the test suite (
npm test)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Development Guidelines
Follow TypeScript best practices
Maintain test coverage above 90%
Update documentation for new features
Follow conventional commit messages
Ensure MCP protocol compliance
License
MIT License - see LICENSE file for details.
Available Tools
11 toolsget-component-detailsB
Get detailed information about a specific component
Inputs: name (required).
get-component-examplesC
Get code examples for a specific component
Inputs: name (required).
get-componentsC
Get all components with optional filtering
Inputs: category, name.
get-design-token-categoriesB
Get all available design token categories
Inputs: no named parameters.
get-design-token-detailsC
Get detailed information about a specific design token
Inputs: name (required).
get-design-tokensC
Get design tokens with optional category filtering
Inputs: category, deprecated.
get-guideline-detailsB
Get detailed information about a specific guideline
Inputs: id (required).
get-guidelinesC
Get design guidelines with optional category filtering
Inputs: category.
search-componentsC
Search components by name, description, or other criteria
Inputs: query (required).
search-design-tokensC
Search design tokens by name or value
Inputs: query (required).
search-guidelinesC
Search guidelines by content, title, or tags
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools have distinct purposes targeting different resources (components, design tokens, guidelines) and actions (get vs. search). However, get-components and search-components could be slightly confusing as both retrieve components, though search adds filtering capabilities.
All tools follow a consistent verb-noun pattern with hyphens (e.g., get-component-details, search-design-tokens). The naming is uniform across all 11 tools, making them predictable and easy to understand.
With 11 tools, the count is well-scoped for a design system server covering components, design tokens, and guidelines. Each tool serves a clear purpose without redundancy, fitting the domain appropriately.
The toolset provides comprehensive read/search coverage for components, design tokens, and guidelines, including details, examples, and filtering. A minor gap is the lack of write/update tools (e.g., create or modify resources), but this is reasonable for a design system focused on retrieval.
Maintenance
Related MCP Connectors
Give AI agents your deeepSpace design system: components, tokens, styles and code mappings.
Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with access to a production-ready design system including Tailwind CSS component patterns, style guides (colors, typography, spacing), and Web Components specifications for consistent UI development.-
- AlicenseNot gradedqualityFmaintenanceProvides AI assistants with access to WordPress Design System component information and design guidance.9GPL 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered access to authoritative design systems knowledge, including W3C standards, WCAG guidelines, and best practices from 188+ curated entries via semantic vector search.9 npm227MIT
- AlicenseAqualityBmaintenanceProvides deterministic, read-only design knowledge for AI coding agents to help them choose visual directions, plan UI states, and compose design tokens, all without network access.6250 npm29MIT