https://github.com/grafana/product-mdc-files
A centralized repository of Model Context Documentation (MDC) files for Grafana products. These files provide rich contextual information to AI assistants working with Grafana codebases.
https://github.com/grafana/product-mdc-files
ai keep loki mdc
Last synced: 10 days ago
JSON representation
A centralized repository of Model Context Documentation (MDC) files for Grafana products. These files provide rich contextual information to AI assistants working with Grafana codebases.
- Host: GitHub
- URL: https://github.com/grafana/product-mdc-files
- Owner: grafana
- License: gpl-3.0
- Created: 2025-10-15T11:26:51.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-15T11:34:48.000Z (9 months ago)
- Last Synced: 2026-06-21T14:57:28.404Z (11 days ago)
- Topics: ai, keep, loki, mdc
- Homepage:
- Size: 97.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Grafana Product MDC Files
A centralized repository of Model Context Documentation (MDC) files for Grafana products. These files provide rich contextual information to AI assistants working with Grafana codebases.
## What are MDC Files?
MDC (Model Context Documentation) files are specialized documentation files designed for use with AI coding assistants like Cursor. They provide comprehensive, structured information about a product's architecture, components, configurations, and patterns in a format optimized for AI consumption.
### Key Characteristics
- **Format**: Markdown files with YAML frontmatter (`.mdc` extension)
- **Location**: Stored in `.cursor/rules/` directories within product folders
- **Purpose**: Give AI assistants deep context about codebases without requiring extensive exploration
- **Structure**: Detailed technical documentation including architecture diagrams, component descriptions, configuration patterns, and best practices
### Benefits
1. **Faster Development**: AI assistants can provide accurate suggestions without searching the entire codebase
2. **Consistency**: Ensures AI recommendations align with product architecture and conventions
3. **Onboarding**: New team members (and AI assistants) can quickly understand complex systems
4. **Accuracy**: Reduces hallucinations and incorrect suggestions from AI tools
5. **Maintenance**: Centralized documentation that's easy to update and version control
## Repository Structure
```
product-mdc-files/
├── README.md
├── loki/
│ └── .cursor/
│ └── rules/
│ └── loki-helm-architecture.mdc
├── mimir/
│ └── .cursor/
│ └── rules/
│ └── mimir-architecture.mdc
└── tempo/
└── .cursor/
└── rules/
└── tempo-components.mdc
```
Each product has its own directory containing:
- `.cursor/rules/` - MDC files for that product
- Subdirectories can organize MDC files by topic (helm charts, APIs, microservices, etc.)
## How to Use MDC Files
### For Product Repositories
1. **Symlink or Copy MDC Files**
In your product repository, create a symlink to the relevant MDC files:
```bash
# From your product repo
ln -s /path/to/product-mdc-files/loki/.cursor .cursor
```
Or copy them directly:
```bash
cp -r /path/to/product-mdc-files/loki/.cursor .cursor/
```
2. **MDC Files Are Automatically Loaded**
When you open your repository in Cursor, the AI assistant will automatically have access to the context in these files.
### For AI Assistants (Cursor)
MDC files can be referenced in two ways:
1. **Always Apply** (Auto-loaded)
```yaml
---
alwaysApply: true
---
```
Files with `alwaysApply: true` are automatically included in every AI conversation.
2. **On-Demand** (Manual reference)
```yaml
---
alwaysApply: false
---
```
Files with `alwaysApply: false` can be manually referenced when needed:
- Use `@filename.mdc` in your prompts
- Or Cursor may automatically load them based on context
### Best Practices
1. **Keep MDC Files Updated**: Update MDC files when architecture or patterns change
2. **Specific Over General**: Create focused MDC files for specific topics rather than monolithic documents
3. **Include Examples**: Provide code examples and configuration snippets
4. **Cross-Reference**: Link related MDC files and external documentation
5. **Version Control**: Commit MDC files alongside code changes
## Creating New MDC Files
### Basic Template
```markdown
---
alwaysApply: false
---
# Product Name - Component/Topic
## Overview
Brief description of what this document covers.
## Architecture
High-level architecture information, diagrams (ASCII art works well).
## Components
Detailed breakdown of components, their responsibilities, and interactions.
## Configuration
Key configuration patterns, values, and best practices.
## Common Patterns
Frequently used code patterns and conventions.
## Troubleshooting
Common issues and how to resolve them.
## References
Links to additional documentation, repos, or resources.
```
### Content Guidelines
1. **Be Comprehensive**: Include all relevant technical details
2. **Use Structure**: Headers, lists, code blocks, and tables for clarity
3. **ASCII Diagrams**: Use text-based diagrams (they work well for AI parsing)
4. **Code Examples**: Include real, working code snippets
5. **Update Metadata**: Use frontmatter to control when files are loaded
## Contributing
To add or update MDC files:
1. **Create Product Directory**: If it doesn't exist, create `product-name/.cursor/rules/`
2. **Add MDC File**: Create descriptive `.mdc` files with proper frontmatter
3. **Document Structure**: Update this README if adding new products
4. **Submit PR**: Include a description of what context the MDC file provides
## Current Products
### Loki
- **loki-helm-architecture.mdc**: Complete Helm chart architecture, deployment modes, components, and configuration patterns
### [Add More Products Here]
## Support
For questions or issues:
- Open an issue in this repository
- Reach out to the DevEx team
- Check Cursor documentation for MDC file specifications
## License
See [LICENSE](LICENSE) file for details.