Augments

Custom Frameworks

Learn how to add custom frameworks to the Augments MCP Server with hot-reloading, validation, and advanced configuration options.

Custom Framework System
The Augments MCP Server uses a flexible JSON-based configuration system for frameworks
JSON Configuration
Structured schema
Hot-Reloading
Real-time updates
Validation
Schema enforcement
Framework Configuration Schema
Complete specification of the framework configuration format

Required Fields

name
string
Required

Unique identifier for the framework (alphanumeric, hyphens, underscores only)

Example: my-custom-framework
display_name
string
Required

Human-readable name shown in documentation and search results

Example: My Custom Framework
category
string
Required

Framework category for organization and filtering

Example: web, backend, mobile, ai-ml, design, tools, database
type
string
Required

Descriptive type of the framework

Example: React Framework, CSS Library, Build Tool
sources
object
Required

Documentation sources configuration with GitHub and/or website

Example: { documentation: { github: {...}, website: '...' } }
context_files
array
Required

Important documentation files to include in context

Example: ['README.md', 'docs/getting-started.md']
key_features
array
Required

Main features and capabilities for search and discovery

Example: ['hot-reload', 'typescript-support', 'component-based']
common_patterns
array
Required

Common usage patterns and architectural approaches

Example: ['component-composition', 'state-management', 'routing']

Optional Fields

version
string
Optional

Version tracking (defaults to 'latest')

Example: latest, v2.1.0, canary
sections
object
Optional

Named section mappings for specific documentation areas

Example: { 'installation': '/docs/installation', 'first-steps': '/docs/first-steps' }
priority
number
Optional

Search ranking priority (0-100, higher = more important, default: 50)

Example: 75 for popular frameworks, 25 for specialized tools
Complete Framework Examples
Real-world examples demonstrating different configuration patterns

Basic Framework Configuration

Minimal configuration for a simple framework with GitHub documentation.

frameworks/web/my-framework.json
{
  "name": "my-framework",
  "display_name": "My Framework",
  "category": "web",
  "type": "React Framework",
  "version": "latest",
  "sources": {
    "documentation": {
      "github": {
        "repo": "myorg/my-framework",
        "docs_path": "docs",
        "branch": "main"
      }
    }
  },
  "context_files": [
    "README.md",
    "docs/getting-started.md",
    "docs/api-reference.md"
  ],
  "key_features": [
    "fast-builds",
    "hot-reload",
    "typescript-support"
  ],
  "common_patterns": [
    "component-architecture",
    "state-management"
  ],
  "priority": 60
}
Hot-Reloading System
The MCP server automatically detects and reloads framework configurations

How It Works

File System Monitoring

  • • Watches the frameworks directory for changes
  • • Detects .json file modifications, additions, deletions
  • • Triggers automatic reloading without server restart
  • • Provides real-time feedback on validation errors

Validation & Error Handling

  • • Validates configuration against schema
  • • Checks required fields and data types
  • • Verifies GitHub repository access
  • • Graceful fallback for invalid configurations

Development Workflow

1. Create Framework File

frameworks/my-category/my-framework.json

2. Edit Configuration

Make changes to your framework configuration file. The server automatically detects changes.

3. Validation Feedback

Check server logs for validation results. Invalid configurations are logged with specific error messages.

4. Test Integration

Use MCP tools to verify your framework is available and documentation is accessible.

Validation Rules & Best Practices
Understanding validation requirements and optimization strategies

Validation Requirements

Naming Conventions

  • • Framework name: alphanumeric, hyphens, underscores only
  • • Use lowercase for consistency
  • • Avoid spaces and special characters
  • • Keep names concise but descriptive

Category Requirements

  • • Must use predefined categories
  • • Categories: web, backend, mobile, ai-ml, design, tools, database
  • • Choose the most appropriate primary category
  • • Use tags for cross-category features

Best Practices

Priority Guidelines

  • • 90-100: Major frameworks (React, Next.js, Django)
  • • 70-89: Popular specialized tools (Tailwind CSS, FastAPI)
  • • 50-69: Standard frameworks and libraries
  • • 25-49: Niche or experimental frameworks

Documentation Strategy

  • • Include both GitHub and website sources for redundancy
  • • Specify the most relevant documentation files
  • • Use stable branches (main, master) for consistency
  • • Test source accessibility before submission

Feature & Pattern Selection

  • • Focus on distinctive features that users search for
  • • Include architectural patterns and usage approaches
  • • Use consistent terminology across similar frameworks
  • • Balance comprehensiveness with clarity
Common Issues & Solutions
Troubleshooting framework configuration problems

❌ Invalid Name Format

Framework names must contain only alphanumeric characters, hyphens, and underscores.

// ❌ Invalid
"name": "My Framework!"
"name": "framework.js"
"name": "framework (v2)"

// ✅ Valid  
"name": "my-framework"
"name": "framework_js"
"name": "framework-v2"

⚠️ Missing Required Fields

Ensure all required fields are present in your configuration.

Required: name, display_name, category, type, sources, context_files, key_features, common_patterns

⚠️ Invalid Category

Categories must be one of the predefined values.

// ❌ Invalid
"category": "frontend"
"category": "devtools"

// ✅ Valid
"category": "web"
"category": "tools"

💡 GitHub Access Issues

Ensure repository URLs are correct and accessible.

• Check repository visibility (public repositories preferred)

• Verify branch names (main vs master)

• Confirm documentation path exists

• Test with GitHub token for better rate limits