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
- Installation
- Quick Start
- Configuration
- Usage
- MCP Client Setup
- Development
- API Documentation
- Troubleshooting
- Contributing
- License
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 build
Install as Global Package
# Install globally (after building)
npm install -g .
# Or link for development
npm link
Quick 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 debug
2. Test the Server
# Test server functionality
npm test
# Run integration tests
npm run test:integration
3. 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 |
|---|---|---|---|
MCP_DATA_PATH | Path to design system data files | ./data | /path/to/design-data |
MCP_LOG_LEVEL | Logging level | info | debug, warn, error |
MCP_ENABLE_FILE_WATCHING | Enable automatic data reloading | true | false |
MCP_CACHE_TTL | Cache time-to-live in seconds | 300 | 600 |
MCP_MAX_CONCURRENT_REQUESTS | Maximum concurrent requests | 100 | 50 |
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 information
Usage
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 start
Available 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 clean
Project 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 documentation
Testing
# 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:ci
Adding 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 start
Problem: Server starts but no tools are available
Error: No tools found
Solution: 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 start
Data Loading Issues
Problem: Design system data not loading
Error: Failed to load design system data
Solution: 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 start
Problem: File watching not working
Warning: File watching disabled
Solution: 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 server
Solution: 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 available
Solution: 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.js
Performance Issues
Problem: Slow response times
Warning: Tool call took longer than expected
Solution: 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:performance
Problem: High memory usage
Warning: High memory usage detected
Solution: 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 start
Debug 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 --verbose
Debug 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.log
Health 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-data
Getting Help
- Check the logs: Enable debug logging to see detailed error information
- Validate data: Run
npm run validate-datato check data file integrity - Test 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.