# 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](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage](#usage)
- [MCP Client Setup](#mcp-client-setup)
- [Development](#development)
- [API Documentation](#api-documentation)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Node.js 18+ 
- npm or yarn package manager

### Install from Source

```bash
# 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

```bash
# Install globally (after building)
npm install -g .

# Or link for development
npm link
```

## Quick Start

### 1. Start the Server

```bash
# 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

```bash
# Test server functionality
npm test

# Run integration tests
npm run test:integration
```

### 3. Connect an MCP Client

See [MCP Client Setup](#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:

```json
{
  "dataPath": "./data",
  "logLevel": "info",
  "enableFileWatching": true,
  "cacheTTL": 300,
  "maxConcurrentRequests": 100,
  "server": {
    "name": "visa-design-system-mcp",
    "version": "1.0.0"
  }
}
```

### CLI Options

```bash
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

```bash
# 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](./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`

```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

```javascript
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`:

```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

```bash
# 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

```bash
# 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](./API.md).

For usage examples and integration patterns, see [EXAMPLES.md](./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
```bash
npm run build
npm start
```

**Problem**: Server starts but no tools are available
```
Error: No tools found
```

**Solution**: Check data path and file permissions
```bash
# 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
```bash
# 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
```bash
# 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
```json
{
  "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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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)

```bash
# 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:

```bash
# 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](LICENSE) file for details.