Provides access to Visa's Product Design System resources, including design tokens, component specifications, and usage guidelines for consistent UI development.
Click on "Install 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.
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.
Related MCP server: WordPress Design System MCP Server
Node.js 18+
npm or yarn package manager
# Clone the repository
git clone <repository-url>
cd visa-design-system-mcp
# Install dependencies
npm install
# Build the project
npm run build# Install globally (after building)
npm install -g .
# Or link for development
npm link# 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# Test server functionality
npm test
# Run integration tests
npm run test:integrationSee MCP Client Setup for detailed configuration instructions.
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 |
|
|
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"
}
}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# 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 startThe server exposes the following MCP 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
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
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.
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"
}
}
}
}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));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"]
}
}
}# 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├── 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# 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:ciAdd 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
For comprehensive API documentation including all available tools, parameters, and response formats, see API.md.
For usage examples and integration patterns, see EXAMPLES.md.
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 startProblem: 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'));"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.jsProblem: 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 startEnable 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
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.logTest 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-dataCheck the logs: Enable debug logging to see detailed error information
Validate data: Run npm run validate-data to 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 update to 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)
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
Follow TypeScript best practices
Maintain test coverage above 90%
Update documentation for new features
Follow conventional commit messages
Ensure MCP protocol compliance
MIT License - see LICENSE file for details.
Get detailed information about a specific component
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Component name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a read operation ('Get'), but doesn't mention any behavioral traits like authentication requirements, rate limits, error handling, or what 'detailed information' includes (e.g., metadata, dependencies, usage). For a tool with no annotations, this leaves significant gaps in understanding how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's appropriately sized for a simple tool and front-loaded with the core purpose, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks context about usage relative to siblings, behavioral details, or output expectations. For a simple read tool, this is borderline viable but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'name' documented as 'Component name' in the schema. The description adds no additional meaning beyond this, such as format examples (e.g., case sensitivity) or context about what constitutes a valid component name. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific component'), making the purpose understandable. However, it doesn't distinguish this tool from similar siblings like 'get-components' (which likely lists multiple components) or 'get-component-examples' (which might provide usage examples), missing full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-components' (likely for listing), 'search-components' (likely for filtering), and 'get-component-examples' (likely for examples), there's no indication of when this detailed view is appropriate versus other component-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get code examples for a specific component
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Component name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'gets' examples, implying a read operation, but does not describe any behavioral traits such as error handling, response format, or whether it returns all examples or a subset. This leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded with the core purpose, making it easy to parse and understand quickly. This is an example of efficient communication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not explain what the tool returns (e.g., code snippets, links, or structured data) or any limitations. For a tool with no structured behavioral hints, the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'name' parameter documented as 'Component name'. The description adds no additional meaning beyond this, such as format examples or constraints. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('code examples for a specific component'), making it easy to understand what the tool does. However, it does not explicitly differentiate from sibling tools like 'get-component-details' or 'search-components', which might also retrieve component-related information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-component-details', 'get-components', and 'search-components' available, there is no indication of when this tool is appropriate (e.g., for examples only) or when other tools should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all components with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter components by category | |
| name | No | Filter components by name (partial match) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Get all components' but doesn't describe return format, pagination, rate limits, permissions needed, or what 'all' entails (e.g., completeness, ordering). This leaves significant gaps for a read operation with potential data volume concerns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a simple tool, though it could be more front-loaded with critical distinctions from siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and multiple sibling tools, the description is incomplete. It doesn't address key contextual questions: how this differs from 'search-components', what 'all components' returns, or behavioral aspects like response format. The 100% schema coverage helps parameters but doesn't compensate for other gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('category' and 'name') with clear descriptions. The description adds minimal value by mentioning 'optional filtering' but doesn't provide additional context like filter combinations, default behavior without filters, or how filtering interacts with 'all components'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all components with optional filtering' states a clear verb ('Get') and resource ('components'), but it's vague about scope and doesn't differentiate from siblings like 'search-components' or 'get-component-details'. It specifies 'all components' but doesn't clarify if this means all available components or has other limitations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search-components' or 'get-component-details'. It mentions 'optional filtering' but doesn't explain when filtering is appropriate or what distinguishes this tool from other component-related tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all available design token categories
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but doesn't clarify if it requires authentication, has rate limits, returns paginated results, or describes the format of the returned categories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the core purpose and appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no annotations and no output schema, the description is minimally adequate. It states what the tool does but lacks details on behavior, output format, or usage context, leaving gaps that could hinder an agent's understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the absence of inputs. The description adds no parameter information, which is appropriate here, earning a baseline score of 4 for not introducing confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('design token categories'), making it immediately understandable. It distinguishes itself from siblings like 'get-design-token-details' by focusing on categories rather than details, though it doesn't explicitly mention this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over 'get-design-tokens' or 'get-design-token-details', nor does it specify any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific design token
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Design token name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it 'gets' information, implying a read-only operation, but doesn't cover aspects like authentication needs, rate limits, error handling, or what 'detailed information' entails (e.g., format, depth). For a tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every part contributing to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a read operation with one parameter) and lack of annotations or output schema, the description is incomplete. It doesn't explain what 'detailed information' includes, potential response formats, or error cases, leaving gaps for effective tool use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'name' parameter clearly documented as 'Design token name'. The description adds no additional meaning beyond this, such as examples or constraints, so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'detailed information about a specific design token', making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get-design-tokens' (which likely lists tokens) or 'get-design-token-categories' (which might handle categories rather than individual tokens), missing explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-design-tokens' (likely for listing) and 'search-design-tokens' (likely for broader queries), there's no indication of context, prerequisites, or exclusions, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get design tokens with optional category filtering
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter tokens by category (color, typography, spacing, elevation, motion) | |
| deprecated | No | Filter by deprecated status (true for deprecated, false for active) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s] design tokens' but doesn't describe what 'design tokens' are, the return format (e.g., list, object), pagination, rate limits, authentication needs, or error handling. For a read operation with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Get design tokens') and adds essential scope ('with optional category filtering'). There is zero waste, and it's appropriately sized for a simple tool with two optional parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a read operation with filtering), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'design tokens' are, the return format, or behavioral aspects like pagination. While the schema covers parameters well, the overall context for agent usage is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('category' and 'deprecated') fully documented in the schema. The description adds minimal value beyond the schema by mentioning 'optional category filtering', which aligns with the 'category' parameter but doesn't provide additional syntax or format details. The baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Get design tokens with optional category filtering', which specifies the verb ('Get'), resource ('design tokens'), and scope ('with optional category filtering'). It distinguishes from siblings like 'get-design-token-details' (likely for specific tokens) and 'search-design-tokens' (likely for keyword-based queries), though it doesn't explicitly name these alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'optional category filtering' but doesn't specify contexts where filtering is useful, prerequisites, or when to choose this over siblings like 'get-design-token-categories' or 'search-design-tokens'. This leaves the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific guideline
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Guideline ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it 'gets' information, implying a read-only operation, but doesn't disclose behavioral traits such as error handling (e.g., what happens if the ID is invalid), rate limits, authentication needs, or the format/scope of the returned details. This leaves significant gaps for an agent to use it effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what 'detailed information' includes (e.g., content, metadata, examples), error cases, or how it relates to sibling tools. For a tool with one parameter but unknown output behavior, more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'id' parameter documented as 'Guideline ID'. The description adds no additional meaning beyond this, as it only mentions 'a specific guideline' without elaborating on the ID format or source. With high schema coverage, the baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific guideline'), making the purpose understandable. It distinguishes from siblings like 'get-guidelines' (list) and 'search-guidelines' (search), but doesn't explicitly mention how it differs from them beyond being for a 'specific' guideline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need details for a 'specific guideline' (identified by ID), which suggests using this after identifying a guideline via 'get-guidelines' or 'search-guidelines'. However, it doesn't explicitly state when to use this vs. alternatives or any prerequisites like needing the ID first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get design guidelines with optional category filtering
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter guidelines by category |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves guidelines but doesn't cover aspects like pagination, rate limits, authentication needs, or what happens if no guidelines are found. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that clearly states the tool's purpose and key feature (optional filtering). It's front-loaded with no wasted words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits like whether it returns all guidelines or a subset. For a tool with no structured metadata, more context is needed to guide proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'category' parameter. The description adds minimal value by mentioning optional filtering but doesn't provide additional context like valid category values or examples beyond what the schema implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('design guidelines'), and mentions optional filtering by category. However, it doesn't differentiate from sibling tools like 'get-guideline-details' or 'search-guidelines', which limits its score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get-guideline-details' or 'search-guidelines'. It mentions optional filtering but doesn't specify contexts or exclusions for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search components by name, description, or other criteria
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query for components |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches components but doesn't describe how results are returned (e.g., pagination, sorting), what 'other criteria' might include, or any limitations like rate limits or authentication needs. This leaves significant gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function. It's front-loaded with the core action and resource, with no wasted words, though it could be slightly more structured by explicitly listing searchable fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with no annotations and no output schema, the description is incomplete. It doesn't explain the return format, result limitations, or how 'other criteria' work, which are critical for effective use. This falls short of what's needed for a tool with such contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'query' documented as 'Search query for components'. The description adds that the query can search by name, description, or other criteria, providing some extra context beyond the schema, but it doesn't detail syntax or format. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool searches components by name, description, or other criteria, which clarifies the verb (search) and resource (components). However, it doesn't differentiate from sibling tools like 'get-components' (which likely lists all components) or 'search-design-tokens' (which searches a different resource), leaving the purpose somewhat vague in context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over 'get-components' for listing all components or 'search-design-tokens' for searching design tokens, nor does it specify any prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search design tokens by name or value
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query for token names or values |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions searching by name or value but doesn't cover critical aspects like whether it's a read-only operation, if it requires authentication, how results are returned (e.g., pagination, format), or any rate limits. For a search tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, consisting of a single sentence that directly states the tool's function. There is no wasted language or redundancy, making it efficient for quick understanding by an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search operation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., read-only status, error handling), usage context compared to siblings, and output format. While the schema covers parameters well, the overall context for effective tool invocation is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'query' parameter documented as 'Search query for token names or values'. The description adds minimal value beyond this, as it essentially restates the schema's purpose without providing additional context like search syntax, case sensitivity, or examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching design tokens by name or value. It specifies the verb 'search' and the resource 'design tokens', making it understandable. However, it doesn't explicitly differentiate from sibling tools like 'get-design-tokens' or 'search-components', which might offer similar functionality for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like 'get-design-tokens' (likely for listing all tokens) and 'search-components' (for searching components), there is no indication of when this tool is preferred, such as for fuzzy matching or specific token attributes. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search guidelines by content, title, or tags
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query for guidelines |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the search functionality but doesn't describe what the search returns (e.g., list of results, pagination behavior), performance characteristics, or any limitations (e.g., rate limits, authentication needs). This is a significant gap for a search tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality ('Search guidelines') and adds specific detail ('by content, title, or tags') without unnecessary elaboration. Every word earns its place, making it appropriately concise for a straightforward search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., a list of guideline objects, search metadata), how results are structured, or any error conditions. For a search tool with no structured output documentation, this leaves critical gaps for an AI agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'query' documented as 'Search query for guidelines'. The description adds marginal value by specifying the searchable fields ('content, title, or tags'), but doesn't provide syntax examples, query format details, or behavioral context beyond what the schema already implies. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and resource ('guidelines'), and specifies the searchable fields ('by content, title, or tags'), which distinguishes it from generic search tools. However, it doesn't explicitly differentiate from sibling tools like 'search-components' or 'search-design-tokens' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get-guidelines' or 'get-guideline-details'. It lacks context about prerequisites, typical use cases, or any explicit 'when-not-to-use' scenarios, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
Serves your design system and coding standards to coding agents, so they stop guessing.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/MarySuneela/mcp-vpds'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
