README.md•5.04 kB
# Best Practices MCP Server
A Model Context Protocol (MCP) server that provides Python coding best practices and guidelines for general coding and API development using FastAPI.
## Features
- **Search Best Practices**: Search by keyword across all categories
- **Category Browsing**: Explore practices by category (general_coding, fastapi_specific, performance, code_quality)
- **Code Examples**: Get practical code examples for specific topics
- **Code Review**: Analyze code against best practices with specific recommendations
- **Improvement Suggestions**: Get prioritized, actionable improvements with before/after examples
- **MCP Resources**: Access best practices via URI (e.g., `bestpractices://fastapi/async_operations`)
- **Pre-built Prompts**: Quick access to common tasks like code review and examples
## Installation
```bash
pip install -r requirements.txt
```
## Configuration
The server supports the following environment variables:
- `BEST_PRACTICES_FILE`: Path to the best practices JSON file (default: `data/python_best_practices.json`)
- `LOG_LEVEL`: Logging level (default: `INFO`)
Example:
```bash
export BEST_PRACTICES_FILE=/path/to/custom_practices.json
export LOG_LEVEL=DEBUG
```
## Running the Server
```bash
python bestpractices_mcp_server.py
```
## Usage with Kiro IDE
1. Add the server to your MCP configuration (`.kiro/settings/mcp.json`):
```json
{
"mcpServers": {
"bestpractices": {
"command": "python",
"args": ["/path/to/bestpractices_mcp_server.py"],
"env": {
"BEST_PRACTICES_FILE": "data/python_best_practices.json"
}
}
}
}
```
2. Restart Kiro IDE or reconnect the MCP server
3. Use the tools in your AI assistant conversations
## Available Tools
### search_best_practices
Search for best practices by keyword.
```python
search_best_practices(keyword="async")
```
### get_practice_by_category
Get practices for a specific category or topic.
```python
get_practice_by_category(category="fastapi_specific", topic="pydantic_models")
```
### list_categories
List all available categories.
```python
list_categories()
```
### get_examples_tool
Get code examples for a specific topic.
```python
get_examples_tool(topic="type_hints")
```
### review_code
Review code against best practices.
```python
review_code(code="def test(): pass", context="general")
```
### suggest_improvements
Get improvement suggestions for code.
```python
suggest_improvements(code="def test(): pass", focus_area="type_hints")
```
## Available Resources
Access best practices directly via URI:
- `bestpractices://general/{topic}` - General Python practices
- `bestpractices://fastapi/{topic}` - FastAPI-specific practices
- `bestpractices://performance/{topic}` - Performance optimization
- `bestpractices://code_quality/{topic}` - Code quality practices
- `bestpractices://all` - Complete guide
## Available Prompts
- `review_python_code` - Comprehensive Python code review
- `review_fastapi_endpoint` - FastAPI-specific code review
- `suggest_code_improvements` - Get improvement suggestions
- `show_examples` - Retrieve examples for a topic
## Best Practices Database
The server reads from `data/python_best_practices.json` which contains:
- **general_coding**: Naming conventions, type hints, error handling, documentation, code organization
- **fastapi_specific**: Routes, Pydantic models, dependency injection, async operations, middleware, security
- **performance**: Caching, database optimization
- **code_quality**: Linting, logging
The database is read dynamically on each request, so updates are reflected immediately without restarting the server.
## Examples
The `examples/` directory contains usage examples demonstrating the server's functionality:
- **search_example.py** - Search for best practices by keyword
- **code_review_example.py** - Review code against best practices
- **resource_access_example.py** - Access practices via categories and topics
Run examples:
```bash
python examples/search_example.py
python examples/code_review_example.py
python examples/resource_access_example.py
```
See `examples/README.md` for detailed documentation.
## Development
### Running Tests
```bash
pytest test_data_manager.py -v
```
### Adding New Best Practices
Edit `data/python_best_practices.json` and add your practices following the structure:
```json
{
"python_best_practices": {
"category_name": {
"topic_name": {
"description": "Description of the practice",
"examples": {
"example_name": "code example"
}
}
}
}
}
```
## Troubleshooting
### Server won't start
- Check that `data/python_best_practices.json` exists
- Verify the JSON file is valid
- Check file permissions
### No results from search
- Verify the keyword exists in the database
- Try broader search terms
- Use `list_categories()` to see available topics
### Tools not appearing in Kiro
- Verify MCP configuration is correct
- Restart Kiro IDE
- Check server logs for errors
## License
MIT License