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 filtering
• search-design-tokens - Search tokens by name or value
• get-design-token-details - Get detailed token information
• get-design-token-categories - List all token categories

Component Tools

• get-components - List all components with optional filtering
• get-component-details - Get detailed component specifications
• get-component-examples - Retrieve component code examples
• search-components - Search components by name or description

Guidelines Tools

• get-guidelines - Retrieve design guidelines with optional filtering
• get-guideline-details - Get detailed guideline information
• search-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

1. Add new MCP tools: Implement in respective service files
2. Update data schemas: Modify JSON schemas in src/schemas/
3. Add tests: Create corresponding test files
4. 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_FILE environment 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

1. Check the logs: Enable debug logging to see detailed error information
2. Validate data: Run npm run validate-data to check data file integrity
3. Test connectivity: Use the health check commands above
4. Review configuration: Verify all paths and environment variables
5. Check permissions: Ensure the server has read access to data files
6. Update dependencies: Run npm update to get the latest versions

If you're still experiencing issues, please:

1. Include debug logs in your issue report
2. Specify your Node.js version (node --version)
3. Describe your MCP client setup
4. Provide your configuration files (with sensitive data removed)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. 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.