Context Guide

Context Guide

Complete reference for creating and configuring context files in the MCP Context Provider.

Overview

Context files are JSON documents that define tool-specific rules, preferences, and automatic corrections. Each file represents a category of tools and their associated context rules.

File Structure

Basic Template

{
  "tool_category": "string",
  "description": "string", 
  "auto_convert": boolean,
  "syntax_rules": {},
  "preferences": {},
  "auto_corrections": {},
  "metadata": {}
}

Field Definitions

Core Fields

tool_category (required)

• Type: String
• Description: Identifier for the tool category
• Examples: "dokuwiki", "terraform", "azure", "git"
• Usage: Used to match tool names and apply appropriate context

description (required)

• Type: String
• Description: Human-readable description of the context
• Example: "DokuWiki-specific context rules and syntax preferences"

auto_convert (optional)

• Type: Boolean
• Default: false
• Description: Whether to automatically apply corrections when tools are used
• Example: true

Rule Sections

syntax_rules (optional)

Defines formatting and syntax conversion rules.

{
  "syntax_rules": {
    "headers": {
      "format": "====== {} ======",
      "levels": {
        "1": "====== {} ======",
        "2": "===== {} ====="
      },
      "avoid": ["#", "##"]
    }
  }
}

Common patterns:

• format: Template string for conversions
• levels: Different formatting levels
• avoid: Patterns to avoid or convert from
• examples: Usage examples

preferences (optional)

User and tool preferences that affect behavior.

{
  "preferences": {
    "date_format": "YYYY-MM-DD",
    "default_location": "westeurope",
    "security": {
      "enable_https_only": true
    }
  }
}

auto_corrections (optional)

Regex-based automatic text corrections.

{
  "auto_corrections": {
    "fix_headers": {
      "pattern": "^(#{1,6})\\s*(.+)$",
      "replacement": "====== $2 ======"
    },
    "fix_links": {
      "pattern": "\\[([^\\]]+)\\]\\(([^)]+)\\)",
      "replacement": "[[$2|$1]]"
    }
  }
}

Fields:

• pattern: Regular expression pattern (JavaScript format)
• replacement: Replacement string (supports capture groups $1, $2)

metadata (recommended)

Information about the context file itself.

{
  "metadata": {
    "version": "1.0.0",
    "last_updated": "2025-01-08",
    "applies_to_tools": [
      "dokuwiki:core_savePage",
      "dokuwiki:*"
    ],
    "priority": "high"
  }
}

Advanced Patterns

Tool Matching

The applies_to_tools array supports various patterns:

{
  "applies_to_tools": [
    "exact:tool_name",           // Exact match
    "prefix:tool_*",             // Prefix match  
    "category:*",                // All tools in category
    "*"                          // All tools (use sparingly)
  ]
}

Nested Rules

Complex rules can be nested:

{
  "syntax_rules": {
    "code_blocks": {
      "languages": {
        "javascript": {
          "format": "<code js>\n{}\n</code>",
          "highlight": true
        },
        "python": {
          "format": "<code python>\n{}\n</code>",
          "highlight": true
        }
      },
      "default": {
        "format": "<code>\n{}\n</code>"
      }
    }
  }
}

Conditional Rules

Rules can include conditions:

{
  "auto_corrections": {
    "environment_specific": {
      "condition": "environment == 'production'",
      "pattern": "console\\.log\\(.*\\)",
      "replacement": "// Removed console.log for production"
    }
  }
}

Best Practices

File Organization

1. One category per file: Keep each tool category in its own file
2. Descriptive names: Use {category}_context.json naming
3. Logical grouping: Group related rules together

Rule Design

1. Start simple: Begin with basic rules and expand
2. Test patterns: Validate regex patterns before deployment
3. Document examples: Include examples for complex rules
4. Version control: Track changes in metadata

Performance

1. Efficient regex: Use non-greedy matches and anchors
2. Limit scope: Target specific patterns, not broad matches
3. Cache results: Rules are loaded once at startup

Examples

Simple Syntax Rules

{
  "tool_category": "markdown",
  "description": "Markdown formatting preferences",
  "auto_convert": true,
  "syntax_rules": {
    "emphasis": {
      "bold": "**{}**",
      "italic": "_{}_",
      "avoid": ["<b>", "<i>"]
    },
    "lists": {
      "unordered": "- {}",
      "ordered": "1. {}",
      "indent": "  "
    }
  },
  "metadata": {
    "version": "1.0.0",
    "applies_to_tools": ["markdown:*"]
  }
}

Complex Auto-Corrections

{
  "auto_corrections": {
    "standardize_dates": {
      "pattern": "(\\d{1,2})/(\\d{1,2})/(\\d{4})",
      "replacement": "$3-$1-$2"
    },
    "fix_spacing": {
      "pattern": "\\s{2,}",
      "replacement": " "
    },
    "remove_trailing_whitespace": {
      "pattern": "\\s+$",
      "replacement": ""
    }
  }
}

Environment-Specific Preferences

{
  "preferences": {
    "development": {
      "debug_mode": true,
      "verbose_logging": true,
      "auto_save": true
    },
    "production": {
      "debug_mode": false,
      "verbose_logging": false,
      "performance_monitoring": true
    }
  }
}

Validation

JSON Schema

Context files should validate against this schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["tool_category", "description"],
  "properties": {
    "tool_category": {"type": "string"},
    "description": {"type": "string"},
    "auto_convert": {"type": "boolean"},
    "syntax_rules": {"type": "object"},
    "preferences": {"type": "object"},
    "auto_corrections": {
      "type": "object",
      "patternProperties": {
        ".*": {
          "type": "object",
          "required": ["pattern", "replacement"],
          "properties": {
            "pattern": {"type": "string"},
            "replacement": {"type": "string"}
          }
        }
      }
    },
    "metadata": {"type": "object"}
  }
}

Common Validation Errors

1. Invalid JSON: Use a JSON validator to check syntax
2. Missing required fields: Ensure tool_category and description are present
3. Invalid regex: Test patterns with online regex tools
4. Circular references: Avoid rules that reference themselves

Testing Context Files

Manual Testing

1. Load test: Add file and restart Claude Desktop
2. Rule test: Verify auto-corrections work as expected
3. Performance test: Check for slow regex patterns

Automated Testing

Create test cases for your context rules:

import json
import re

def test_context_file(file_path):
    with open(file_path) as f:
        context = json.load(f)
    
    # Test auto-corrections
    for name, rule in context.get('auto_corrections', {}).items():
        pattern = rule['pattern']
        replacement = rule['replacement']
        
        # Test with sample text
        test_text = "Sample text for testing"
        result = re.sub(pattern, replacement, test_text)
        
        print(f"Rule '{name}': '{test_text}' → '{result}'")

Troubleshooting

Common Issues

1. Rules not applying: Check auto_convert is true
2. Regex errors: Validate patterns with online tools
3. File not loading: Check JSON syntax and file placement
4. Performance issues: Optimize regex patterns

Debug Output

Enable debug mode to see rule applications:

{
  "env": {
    "DEBUG_MODE": "true"
  }
}

This will log context loading and rule applications to help with troubleshooting.

Migration Guide

From Version 0.x to 1.x

1. Update structure: Add metadata section
2. Rename fields: rules → syntax_rules
3. Add versioning: Include version in metadata
4. Test thoroughly: Verify all rules still work

Adding New Fields

When extending context files:

1. Maintain compatibility: Keep existing fields working
2. Use optional fields: New features should be optional
3. Document changes: Update this guide with new patterns
4. Version appropriately: Increment version numbers

This completes the comprehensive context guide for creating and managing context files in the MCP Context Provider.