{"id":51038870,"url":"https://github.com/grafana/product-mdc-files","last_synced_at":"2026-06-22T09:01:01.224Z","repository":{"id":366367404,"uuid":"1076809159","full_name":"grafana/product-mdc-files","owner":"grafana","description":"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.","archived":false,"fork":false,"pushed_at":"2025-10-15T11:34:48.000Z","size":100,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-21T14:57:28.404Z","etag":null,"topics":["ai","keep","loki","mdc"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T11:26:51.000Z","updated_at":"2025-11-14T05:53:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grafana/product-mdc-files","commit_stats":null,"previous_names":["grafana/product-mdc-files"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/grafana/product-mdc-files","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fproduct-mdc-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fproduct-mdc-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fproduct-mdc-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fproduct-mdc-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/product-mdc-files/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fproduct-mdc-files/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34641636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","keep","loki","mdc"],"created_at":"2026-06-22T09:01:00.143Z","updated_at":"2026-06-22T09:01:01.218Z","avatar_url":"https://github.com/grafana.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafana Product MDC Files\n\nA centralized repository of Model Context Documentation (MDC) files for Grafana products. These files provide rich contextual information to AI assistants working with Grafana codebases.\n\n## What are MDC Files?\n\nMDC (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.\n\n### Key Characteristics\n\n- **Format**: Markdown files with YAML frontmatter (`.mdc` extension)\n- **Location**: Stored in `.cursor/rules/` directories within product folders\n- **Purpose**: Give AI assistants deep context about codebases without requiring extensive exploration\n- **Structure**: Detailed technical documentation including architecture diagrams, component descriptions, configuration patterns, and best practices\n\n### Benefits\n\n1. **Faster Development**: AI assistants can provide accurate suggestions without searching the entire codebase\n2. **Consistency**: Ensures AI recommendations align with product architecture and conventions\n3. **Onboarding**: New team members (and AI assistants) can quickly understand complex systems\n4. **Accuracy**: Reduces hallucinations and incorrect suggestions from AI tools\n5. **Maintenance**: Centralized documentation that's easy to update and version control\n\n## Repository Structure\n\n```\nproduct-mdc-files/\n├── README.md\n├── loki/\n│   └── .cursor/\n│       └── rules/\n│           └── loki-helm-architecture.mdc\n├── mimir/\n│   └── .cursor/\n│       └── rules/\n│           └── mimir-architecture.mdc\n└── tempo/\n    └── .cursor/\n        └── rules/\n            └── tempo-components.mdc\n```\n\nEach product has its own directory containing:\n- `.cursor/rules/` - MDC files for that product\n- Subdirectories can organize MDC files by topic (helm charts, APIs, microservices, etc.)\n\n## How to Use MDC Files\n\n### For Product Repositories\n\n1. **Symlink or Copy MDC Files**\n   \n   In your product repository, create a symlink to the relevant MDC files:\n   ```bash\n   # From your product repo\n   ln -s /path/to/product-mdc-files/loki/.cursor .cursor\n   ```\n   \n   Or copy them directly:\n   ```bash\n   cp -r /path/to/product-mdc-files/loki/.cursor .cursor/\n   ```\n\n2. **MDC Files Are Automatically Loaded**\n   \n   When you open your repository in Cursor, the AI assistant will automatically have access to the context in these files.\n\n### For AI Assistants (Cursor)\n\nMDC files can be referenced in two ways:\n\n1. **Always Apply** (Auto-loaded)\n   ```yaml\n   ---\n   alwaysApply: true\n   ---\n   ```\n   Files with `alwaysApply: true` are automatically included in every AI conversation.\n\n2. **On-Demand** (Manual reference)\n   ```yaml\n   ---\n   alwaysApply: false\n   ---\n   ```\n   Files with `alwaysApply: false` can be manually referenced when needed:\n   - Use `@filename.mdc` in your prompts\n   - Or Cursor may automatically load them based on context\n\n### Best Practices\n\n1. **Keep MDC Files Updated**: Update MDC files when architecture or patterns change\n2. **Specific Over General**: Create focused MDC files for specific topics rather than monolithic documents\n3. **Include Examples**: Provide code examples and configuration snippets\n4. **Cross-Reference**: Link related MDC files and external documentation\n5. **Version Control**: Commit MDC files alongside code changes\n\n## Creating New MDC Files\n\n### Basic Template\n\n```markdown\n---\nalwaysApply: false\n---\n\n# Product Name - Component/Topic\n\n## Overview\nBrief description of what this document covers.\n\n## Architecture\nHigh-level architecture information, diagrams (ASCII art works well).\n\n## Components\nDetailed breakdown of components, their responsibilities, and interactions.\n\n## Configuration\nKey configuration patterns, values, and best practices.\n\n## Common Patterns\nFrequently used code patterns and conventions.\n\n## Troubleshooting\nCommon issues and how to resolve them.\n\n## References\nLinks to additional documentation, repos, or resources.\n```\n\n### Content Guidelines\n\n1. **Be Comprehensive**: Include all relevant technical details\n2. **Use Structure**: Headers, lists, code blocks, and tables for clarity\n3. **ASCII Diagrams**: Use text-based diagrams (they work well for AI parsing)\n4. **Code Examples**: Include real, working code snippets\n5. **Update Metadata**: Use frontmatter to control when files are loaded\n\n## Contributing\n\nTo add or update MDC files:\n\n1. **Create Product Directory**: If it doesn't exist, create `product-name/.cursor/rules/`\n2. **Add MDC File**: Create descriptive `.mdc` files with proper frontmatter\n3. **Document Structure**: Update this README if adding new products\n4. **Submit PR**: Include a description of what context the MDC file provides\n\n## Current Products\n\n### Loki\n- **loki-helm-architecture.mdc**: Complete Helm chart architecture, deployment modes, components, and configuration patterns\n\n### [Add More Products Here]\n\n## Support\n\nFor questions or issues:\n- Open an issue in this repository\n- Reach out to the DevEx team\n- Check Cursor documentation for MDC file specifications\n\n## License\n\nSee [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fproduct-mdc-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fproduct-mdc-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fproduct-mdc-files/lists"}