2487 Context Guide 789638a4

# 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

```json
{
  "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.

```json
{
  "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.

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

#### `auto_corrections` (optional)
Regex-based automatic text corrections.

```json
{
  "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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```json
{
  "$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:

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

```json
{
  "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.