User GuidesUsing Design Rules

Using Design Rules

Learn how to use MA²D’s built-in design rules to ensure your MCP servers meet quality and compliance standards.

What are Design Rules?

Design rules are automated quality checks that validate your MCP servers against best practices:

  • Naming conventions - snake_case, clear names
  • Documentation - Complete descriptions
  • Schemas - Valid JSON schemas
  • Mock scenarios - Test data coverage
  • Versioning - Semantic versioning
  • And more - 10 rules total

Accessing Design Rules

  1. Open any MCP server
  2. Click the “Compliance” tab
  3. View your compliance score and violations

Understanding Compliance Score

Your server gets a score from 0-100%:

  • 90-100% ✅ Excellent - Ready to publish
  • 70-89% ⚠️ Good - Minor issues
  • 50-69% ⚠️ Fair - Several issues
  • 0-49% ❌ Poor - Major issues

The 10 Design Rules

1. Clear Naming Convention

Rule: Tool, resource, and prompt names must use snake_case

Example:

  • ✅ get_weather
  • ✅ analyze_sales_data
  • ❌ getWeather
  • ❌ AnalyzeSalesData

Fix: Rename to snake_case format

2. Comprehensive Descriptions

Rule: Descriptions must be at least 200 characters

Example:

  • ✅ “Get current weather conditions including temperature, humidity, wind speed, precipitation, and atmospheric pressure for any city worldwide. Supports multiple temperature units (celsius/fahrenheit) and provides real-time data updated every 15 minutes.”
  • ❌ “Get weather”

Fix: Add detailed, helpful descriptions

3. Complete JSON Schemas

Rule: All tools must have valid JSON schemas

Requirements:

  • Valid JSON structure
  • Type definitions for all properties
  • Descriptions for parameters
  • Required fields specified

Fix: Add or update input/output schemas

4. Mock Scenarios Required

Rule: Each tool must have at least one mock scenario

Why: Enables testing without real APIs

Fix: Add mock scenarios with realistic data

5. Version Specified

Rule: Must follow semantic versioning (X.Y.Z)

Example:

  • ✅ 1.0.0
  • ✅ 2.5.1
  • ❌ 1.0
  • ❌ v1

Fix: Use proper semantic versioning

6. Resource URIs Follow Convention

Rule: URIs must follow pattern: protocol://path/resource

Example:

  • ✅ weather://cities/list
  • ✅ data://users/profile
  • ❌ cities_list
  • ❌ /cities/list

Fix: Update to proper URI format

7. Authentication Documented

Rule: If authentication required, document it clearly

Fix: Add authentication requirements in server settings

8. Prompt Templates Use Placeholders

Rule: Prompts must use {variable} syntax

Example:

  • ✅ “Get weather for {city} in {units}”
  • ❌ “Get weather for city in units”

Fix: Add placeholder syntax

9. No Hardcoded Secrets

Rule: No API keys, passwords, or tokens in configurations

Fix: Remove secrets, use environment variables

10. Consistent Error Handling

Rule: Error responses must follow JSON-RPC 2.0 format

Fix: Ensure mock scenarios include error cases

Checking Compliance

View Violations

In the Compliance tab:

  1. See overall score
  2. View list of violations
  3. Each violation shows:
    • Rule name
    • Severity (Error, Warning, Info)
    • Location (which tool/resource)
    • How to fix

Filter Violations

Filter by:

  • Severity level
  • Rule type
  • Tool/Resource/Prompt

Fixing Violations

Priority Order

  1. Errors - Must fix before publishing
  2. Warnings - Should fix for best practices
  3. Info - Optional improvements

Fix Workflow

For each violation:

  1. Click on violation to see details
  2. Click “Go to Issue” to navigate to problem
  3. Fix the issue
  4. Save changes
  5. Return to Compliance tab
  6. See updated score

Bulk Fixes

Fix multiple issues of same type:

  1. Identify pattern (e.g., all descriptions too short)
  2. Fix all instances
  3. Compliance score updates automatically

Customizing Design Rules

Organization-Level Rules

Admins can customize rules:

  1. Go to Settings > Design Rules
  2. Configure each rule:
    • Enable/Disable
    • Set severity
    • Adjust thresholds
    • Add custom rules (enterprise)

Example Customizations

  • Require 300+ character descriptions (instead of 200)
  • Enforce specific naming patterns
  • Require 3+ mock scenarios per tool
  • Custom organization-specific rules

Compliance Best Practices

During Development

  • Check Early - Review compliance as you build
  • Fix Incrementally - Don’t wait until the end
  • Aim for 100% - Strive for perfect compliance

Before Publishing

  • 95%+ Required - Minimum for Anypoint Exchange
  • Review All Violations - Even minor warnings
  • Test Thoroughly - Ensure quality

After Publishing

  • Maintain Compliance - Keep score high
  • Update Regularly - As rules evolve
  • Monitor Trends - Track compliance over time

Compliance Reports

Generate Reports

  1. Go to Compliance tab
  2. Click “Generate Report”
  3. Select format (PDF, CSV, JSON)
  4. Download report

Report Contents

  • Overall score
  • Violation breakdown
  • Historical trends
  • Recommendations

Share Reports

Use reports for:

  • Team reviews
  • Audit purposes
  • Stakeholder updates

Common Issues

”Tool name not snake_case”

Solution: Rename tool from getWeather to get_weather

”Description too short”

Solution: Expand description to 200+ characters with details

”Missing mock scenario”

Solution: Add at least one mock scenario per tool

”Invalid semantic version”

Solution: Change from 1.0 to 1.0.0

Compliance in CI/CD

Automated Checks

Integrate compliance checks:

# Using MA²D API
curl -X GET https://ma2d.vercel.app/api/servers/YOUR_ID/compliance
 
# Check score
if [ $SCORE -lt 95 ]; then
  echo "Compliance too low: $SCORE%"
  exit 1
fi

Pre-Publish Validation

Block publishing if compliance < 95%

Next Steps

Keep your compliance score high for quality, publishable MCP servers! 🎯

Creating Agent CardsPublishing to Exchange