# 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