mirror of
https://github.com/HackSoftware/Django-Styleguide.git
synced 2025-07-23 14:19:45 +03:00
docs: add mcpdoc setup instructions for IDE integration
This commit is contained in:
Dmitry Sichkar
parent
aaf0f70565
commit
f615d46c58
12
README.md
12
README.md
|
|
@ -69,6 +69,8 @@
|
|||
- [Handling updates with a service](#handling-updates-with-a-service)
|
||||
- [DX (Developer Experience)](#dx-developer-experience)
|
||||
- [`mypy` / type annotations](#mypy--type-annotations)
|
||||
- [MCP Documentation Server](#mcp-documentation-server)
|
||||
- [Setting up MCP Documentation Server](#setting-up-mcp-documentation-server)
|
||||
- [Django Styleguide in the Wild](#django-styleguide-in-the-wild)
|
||||
- [Additional resources / Alternatives](#additional-resources--alternatives)
|
||||
- [Inspiration](#inspiration)
|
||||
|
|
@ -334,7 +336,7 @@ This can actually be a downside (_this is not the case, starting from Django 4.1
|
|||
The Django's documentation on constraints is quite lean, so you can check the following articles by Adam Johnson, for examples of how to use them:
|
||||
|
||||
1. [Using Django Check Constraints to Ensure Only One Field Is Set](https://adamj.eu/tech/2020/03/25/django-check-constraints-one-field-set/)
|
||||
1. [Django’s Field Choices Don’t Constrain Your Data](https://adamj.eu/tech/2020/01/22/djangos-field-choices-dont-constrain-your-data/)
|
||||
1. [Django's Field Choices Don't Constrain Your Data](https://adamj.eu/tech/2020/01/22/djangos-field-choices-dont-constrain-your-data/)
|
||||
1. [Using Django Check Constraints to Prevent Self-Following](https://adamj.eu/tech/2021/02/26/django-check-constraints-prevent-self-following/)
|
||||
|
||||
### Properties
|
||||
|
|
@ -2763,6 +2765,14 @@ Additionally, this particular project - <https://github.com/wemake-services/wema
|
|||
|
||||
Figure out what is going to work best for you.
|
||||
|
||||
### MCP Documentation Server
|
||||
|
||||
To enhance the developer experience when working with the Django Styleguide, we provide an MCP (Machine Context Protocol) documentation server that integrates with various IDEs like Cursor, Windsurf, and Claude.
|
||||
|
||||
This allows you to get contextual help and documentation while working with the Django Styleguide directly in your IDE.
|
||||
|
||||
For setup instructions, see [Setting up MCP Documentation Server](tools/setup_mpc.md).
|
||||
|
||||
## Django Styleguide in the Wild
|
||||
|
||||
Here's a collection of different folks & companies, that have found the styleguide useful:
|
||||
|
|
|
|||
71
llms.txt
Normal file
71
llms.txt
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
# Django Styleguide Documentation Index
|
||||
|
||||
This is a documentation index for the Django Styleguide, providing links to key sections and concepts.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
- Overview and Philosophy
|
||||
https://github.com/HackSoftware/Django-Styleguide#overview
|
||||
|
||||
- Models
|
||||
https://github.com/HackSoftware/Django-Styleguide#models
|
||||
- Base Model: https://github.com/HackSoftware/Django-Styleguide#base-model
|
||||
- Validation: https://github.com/HackSoftware/Django-Styleguide#validation---clean-and-full_clean
|
||||
- Properties: https://github.com/HackSoftware/Django-Styleguide#properties
|
||||
- Methods: https://github.com/HackSoftware/Django-Styleguide#methods
|
||||
|
||||
- Services
|
||||
https://github.com/HackSoftware/Django-Styleguide#services
|
||||
- Function-based Services: https://github.com/HackSoftware/Django-Styleguide#example---function-based-service
|
||||
- Class-based Services: https://github.com/HackSoftware/Django-Styleguide#example---class-based-service
|
||||
- Naming Conventions: https://github.com/HackSoftware/Django-Styleguide#naming-convention
|
||||
- Modules: https://github.com/HackSoftware/Django-Styleguide#modules
|
||||
|
||||
- APIs & Serializers
|
||||
https://github.com/HackSoftware/Django-Styleguide#apis--serializers
|
||||
- List APIs: https://github.com/HackSoftware/Django-Styleguide#list-apis
|
||||
- Detail API: https://github.com/HackSoftware/Django-Styleguide#detail-api
|
||||
- Create API: https://github.com/HackSoftware/Django-Styleguide#create-api
|
||||
- Update API: https://github.com/HackSoftware/Django-Styleguide#update-api
|
||||
|
||||
## Project Structure
|
||||
|
||||
- Settings
|
||||
https://github.com/HackSoftware/Django-Styleguide#settings
|
||||
- Environment Variables: https://github.com/HackSoftware/Django-Styleguide#prefixing-environment-variables-with-django_
|
||||
- Integrations: https://github.com/HackSoftware/Django-Styleguide#integrations
|
||||
|
||||
- URLs
|
||||
https://github.com/HackSoftware/Django-Styleguide#urls
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
- Error Handling
|
||||
https://github.com/HackSoftware/Django-Styleguide#errors--exception-handling
|
||||
- Exception Handling Overview: https://github.com/HackSoftware/Django-Styleguide#how-exception-handling-works-in-the-context-of-drf
|
||||
- HackSoft's Approach: https://github.com/HackSoftware/Django-Styleguide#approach-2---hacksofts-proposed-way
|
||||
|
||||
- Testing
|
||||
https://github.com/HackSoftware/Django-Styleguide#testing
|
||||
- Overview: https://github.com/HackSoftware/Django-Styleguide#overview-1
|
||||
- Naming Conventions: https://github.com/HackSoftware/Django-Styleguide#naming-conventions
|
||||
- Factories: https://github.com/HackSoftware/Django-Styleguide#factories
|
||||
|
||||
- Celery Integration
|
||||
https://github.com/HackSoftware/Django-Styleguide#celery
|
||||
- Basics: https://github.com/HackSoftware/Django-Styleguide#the-basics
|
||||
- Error Handling: https://github.com/HackSoftware/Django-Styleguide#error-handling
|
||||
- Periodic Tasks: https://github.com/HackSoftware/Django-Styleguide#periodic-tasks
|
||||
|
||||
## Developer Experience
|
||||
|
||||
- Type Annotations & mypy
|
||||
https://github.com/HackSoftware/Django-Styleguide#mypy--type-annotations
|
||||
|
||||
## Examples & Resources
|
||||
|
||||
- Django Styleguide Example Project
|
||||
https://github.com/HackSoftware/Django-Styleguide-Example
|
||||
|
||||
- Additional Resources
|
||||
https://github.com/HackSoftware/Django-Styleguide#additional-resources--alternatives
|
||||
125
tools/setup_mpc.md
Normal file
125
tools/setup_mpc.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
# Setting up MCP Documentation Server
|
||||
|
||||
This guide explains how to set up the MCP documentation server for the Django Styleguide, which allows IDEs like Cursor and Windsurf to access the documentation context.
|
||||
|
||||
## Overview
|
||||
|
||||
We use [mcpdoc](https://github.com/langchain-ai/mcpdoc) to expose our `llms.txt` documentation index to IDEs. This allows for better context when working with the Django Styleguide.
|
||||
|
||||
## Installation
|
||||
|
||||
1. First, install mcpdoc:
|
||||
|
||||
```bash
|
||||
pip install mcpdoc
|
||||
```
|
||||
|
||||
2. Configure your IDE to use the MCP server:
|
||||
|
||||
### For Cursor
|
||||
|
||||
1. Open Cursor settings and navigate to the MCP configuration
|
||||
2. Create or edit `~/.cursor/mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"django-styleguide-docs-mcp": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"--from",
|
||||
"mcpdoc",
|
||||
"mcpdoc",
|
||||
"--urls",
|
||||
"DjangoStyleguide:https://raw.githubusercontent.com/HackSoftware/Django-Styleguide/master/llms.txt",
|
||||
"--transport",
|
||||
"stdio"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
3. Update Cursor Global Rules (Settings/Rules) with:
|
||||
|
||||
```
|
||||
for ANY question about Django Styleguide, use the django-styleguide-docs-mcp server to help answer --
|
||||
+ call list_doc_sources tool to get the available llms.txt file
|
||||
+ call fetch_docs tool to read it
|
||||
+ reflect on the urls in llms.txt
|
||||
+ reflect on the input question
|
||||
+ call fetch_docs on any urls relevant to the question
|
||||
+ use this to answer the question
|
||||
```
|
||||
|
||||
### For Windsurf
|
||||
|
||||
1. Open Cascade with `CMD+L` (on Mac)
|
||||
2. Click Configure MCP to open `~/.codeium/windsurf/mcp_config.json`
|
||||
3. Add the same configuration as shown above for Cursor
|
||||
4. Update Windsurf Rules/Global rules with the same rule pattern shown above
|
||||
|
||||
### For Claude Desktop
|
||||
|
||||
1. Open Settings/Developer to update `~/Library/Application\ Support/Claude/claude_desktop_config.json`
|
||||
2. Add the same configuration as shown above
|
||||
3. Restart Claude Desktop app
|
||||
|
||||
Note: Currently, Claude Desktop doesn't support global rules, so you'll need to include the rules in your prompts:
|
||||
|
||||
```
|
||||
<rules>
|
||||
for ANY question about Django Styleguide, use the django-styleguide-docs-mcp server to help answer --
|
||||
+ call list_doc_sources tool to get the available llms.txt file
|
||||
+ call fetch_docs tool to read it
|
||||
+ reflect on the urls in llms.txt
|
||||
+ reflect on the input question
|
||||
+ call fetch_docs on any urls relevant to the question
|
||||
</rules>
|
||||
```
|
||||
|
||||
### For Claude Code
|
||||
|
||||
In a terminal after installing Claude Code, run:
|
||||
|
||||
```bash
|
||||
claude mcp add-json django-styleguide-docs '{"type":"stdio","command":"uvx" ,"args":["--from", "mcpdoc", "mcpdoc", "--urls", "DjangoStyleguide:https://raw.githubusercontent.com/HackSoftware/Django-Styleguide/master/llms.txt"]}' -s local
|
||||
```
|
||||
|
||||
## Testing the Setup
|
||||
|
||||
To test if the setup is working:
|
||||
|
||||
1. Open your IDE
|
||||
2. Ask a question about the Django Styleguide
|
||||
3. The IDE should use the MCP server to fetch relevant documentation and provide context-aware answers
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into issues with Python version incompatibility, you can explicitly specify the filepath to the Python executable in the `uvx` command:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"django-styleguide-docs-mcp": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"--python",
|
||||
"/path/to/python",
|
||||
"--from",
|
||||
"mcpdoc",
|
||||
"mcpdoc",
|
||||
"--urls",
|
||||
"DjangoStyleguide:https://raw.githubusercontent.com/HackSoftware/Django-Styleguide/master/llms.txt",
|
||||
"--transport",
|
||||
"stdio",
|
||||
"--port",
|
||||
"8082",
|
||||
"--host",
|
||||
"localhost"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user