Best Practices MCP Server

# Design Document ## Overview The Best Practices MCP Server is a FastMCP-based Model Context Protocol server that provides Python coding best practices and guidelines to AI assistants. The server exposes tools for searching and retrieving coding standards, resources for direct access to best practices content, and prompts for common development tasks. The server reads from a JSON-based knowledge base dynamically, allowing updates without restarts. ## Architecture ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ AI Assistant (Kiro IDE) │ └────────────────────────┬────────────────────────────────────┘ │ MCP Protocol │ ┌────────────────────────▼────────────────────────────────────┐ │ Best Practices MCP Server (FastMCP) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Tools │ │ Resources │ │ Prompts │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ └──────────────────┼──────────────────┘ │ │ │ │ │ ┌────────▼────────┐ │ │ │ Data Manager │ │ │ └────────┬────────┘ │ └────────────────────────────┼────────────────────────────────┘ │ ┌────────▼────────┐ │ JSON Database │ │ (python_best_ │ │ practices.json)│ └─────────────────┘ ``` ### Component Responsibilities 1. **Tools Layer**: Exposes MCP tools for searching, retrieving, and analyzing best practices 2. **Resources Layer**: Provides URI-based access to best practices content 3. **Prompts Layer**: Offers pre-built prompt templates for common tasks 4. **Data Manager**: Handles JSON file reading, parsing, validation, and search operations 5. **JSON Database**: Stores the best practices knowledge base ## Components and Interfaces ### 1. Data Manager Module **Purpose**: Centralized module for loading, parsing, and querying the best practices database. **Key Functions**: - `load_best_practices() -> dict`: Loads and validates JSON file - `search_practices(keyword: str) -> list`: Searches across all practices - `get_category(category: str) -> dict`: Retrieves specific category - `list_all_categories() -> list`: Lists available categories - `get_examples(topic: str) -> list`: Retrieves code examples - `find_similar_topics(query: str) -> list`: Suggests similar topics using fuzzy matching **Error Handling**: - File not found: Return clear error with file path - Invalid JSON: Return parsing error with line number - Missing keys: Return validation error with expected structure ### 2. Tools Module **Tool Definitions**: #### search_best_practices ```python @mcp.tool() def search_best_practices(keyword: str) -> dict: """ Search for best practices by keyword across all categories. Args: keyword: Search term to find in descriptions, examples, or topic names Returns: Dictionary containing matching practices with descriptions, examples, and related topics """ ``` #### get_practice_by_category ```python @mcp.tool() def get_practice_by_category(category: str, topic: str = None) -> dict: """ Retrieve best practices for a specific category or topic. Args: category: Category name (general_coding, fastapi_specific, performance, code_quality) topic: Optional specific topic within the category Returns: Dictionary containing practice details with descriptions, examples, and links """ ``` #### list_categories ```python @mcp.tool() def list_categories() -> dict: """ List all available best practice categories. Returns: Dictionary with category names, descriptions, and topic counts """ ``` #### get_examples ```python @mcp.tool() def get_examples(topic: str) -> dict: """ Get code examples for a specific topic. Args: topic: Topic name to retrieve examples for Returns: Dictionary containing code examples with context and explanations """ ``` #### review_code ```python @mcp.tool() def review_code(code: str, context: str = "general") -> dict: """ Review code against best practices and provide feedback. Args: code: Code snippet to review context: Context type - "general" or "fastapi" Returns: Dictionary with violations, recommendations, and good patterns identified """ ``` #### suggest_improvements ```python @mcp.tool() def suggest_improvements(code: str, focus_area: str = None) -> dict: """ Suggest specific improvements for code with before/after examples. Args: code: Code snippet to improve focus_area: Optional area to focus on (error_handling, async, security, etc.) Returns: Dictionary with prioritized improvements, code examples, and trade-offs """ ``` ### 3. Resources Module **Resource URIs**: - `bestpractices://general/{topic}`: Access general coding practices - `bestpractices://fastapi/{topic}`: Access FastAPI-specific practices - `bestpractices://performance/{topic}`: Access performance optimization practices - `bestpractices://code_quality/{topic}`: Access code quality practices - `bestpractices://all`: Access complete best practices guide **Resource Handler**: ```python @mcp.resource("bestpractices://{category}/{topic}") def get_practice_resource(category: str, topic: str) -> str: """ Retrieve best practice content as a resource. Returns formatted markdown content with descriptions, examples, and links. """ ``` ### 4. Prompts Module **Prompt Definitions**: #### review_python_code ```python @mcp.prompt() def review_python_code() -> list: """ Prompt for comprehensive Python code review. Requests user's code and performs analysis against general Python best practices. """ ``` #### review_fastapi_endpoint ```python @mcp.prompt() def review_fastapi_endpoint() -> list: """ Prompt for FastAPI-specific code review. Requests FastAPI code and analyzes against FastAPI best practices. """ ``` #### suggest_code_improvements ```python @mcp.prompt() def suggest_code_improvements() -> list: """ Prompt for getting prioritized improvement suggestions. Requests code and provides actionable improvements with examples. """ ``` #### show_examples ```python @mcp.prompt() def show_examples() -> list: """ Prompt for retrieving examples for a specific topic. Requests topic name and returns relevant code examples. """ ``` ## Data Models ### Best Practices Database Structure ```json { "python_best_practices": { "category_name": { "topic_name": { "description": "string", "examples": { "example_name": "string (code or text)" } } } } } ``` ### Tool Response Models #### SearchResult ```python { "matches": [ { "category": "string", "topic": "string", "description": "string", "examples": ["string"], "related_topics": ["string"] } ], "count": int, "suggestions": ["string"] # If no exact matches } ``` #### CategoryResult ```python { "category": "string", "topics": [ { "name": "string", "description": "string", "examples": ["string"], "documentation_links": ["string"] } ] } ``` #### CodeReview ```python { "violations": [ { "severity": "critical|important|nice-to-have", "issue": "string", "line": int, "recommendation": "string", "example": "string" } ], "good_patterns": ["string"], "overall_score": int, # 0-100 "summary": "string" } ``` #### ImprovementSuggestion ```python { "improvements": [ { "priority": "critical|important|nice-to-have", "description": "string", "before": "string", "after": "string", "trade_offs": "string", "related_practice": "string" } ] } ``` ## Correctness Properties *A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* ### Property 1: Search completeness *For any* keyword and database state, all returned search results should contain the keyword in their description, examples, or topic names. **Validates: Requirements 1.1** ### Property 2: Search result structure *For any* search that returns results, each result should include description, examples, and related practices fields. **Validates: Requirements 1.2** ### Property 3: Search fallback suggestions *For any* keyword that produces no exact matches, the system should return suggested similar topics. **Validates: Requirements 1.3** ### Property 4: Search result organization *For any* search with multiple results, results should be grouped by category. **Validates: Requirements 1.4** ### Property 5: Category completeness *For any* valid category in the database, requesting it should return all topics within that category. **Validates: Requirements 2.1** ### Property 6: Category response structure *For any* category request, each topic should include description, examples, and documentation links. **Validates: Requirements 2.2** ### Property 7: Invalid category suggestions *For any* invalid category name, the system should suggest valid categories based on similarity. **Validates: Requirements 2.3** ### Property 8: Hierarchical structure preservation *For any* category with nested topics, the response should preserve the hierarchical structure. **Validates: Requirements 2.5** ### Property 9: Category list completeness *For any* database state, the category list should include all top-level categories from the database. **Validates: Requirements 3.1** ### Property 10: Category list structure *For any* category in the list, it should include a description and topic count. **Validates: Requirements 3.2, 3.3** ### Property 11: Dynamic database reloading *For any* database modification, the next request should reflect the updated content. **Validates: Requirements 3.4, 9.2** ### Property 12: Example completeness *For any* valid topic, all associated code examples should be returned. **Validates: Requirements 4.1** ### Property 13: Example structure *For any* returned example, it should include context and explanation. **Validates: Requirements 4.2** ### Property 14: Example fallback suggestions *For any* topic without examples, the system should suggest related topics that have examples. **Validates: Requirements 4.3** ### Property 15: Example formatting *For any* code example, it should be formatted with proper syntax highlighting markers (markdown code blocks). **Validates: Requirements 4.4** ### Property 16: Code review references database *For any* code review, identified issues should correspond to best practices in the database. **Validates: Requirements 5.1** ### Property 17: Context detection accuracy *For any* code input, the detected context (Python vs FastAPI) should match the actual code type, and applied guidelines should come from the appropriate category. **Validates: Requirements 5.3** ### Property 18: Review feedback actionability *For any* code review, all feedback should include example corrections. **Validates: Requirements 5.5** ### Property 19: Improvement concreteness *For any* improvement suggestion, it should include concrete code modifications. **Validates: Requirements 6.1** ### Property 20: Improvement prioritization *For any* improvement suggestion, it should have a priority level (critical, important, or nice-to-have). **Validates: Requirements 6.2** ### Property 21: Improvement examples *For any* improvement suggestion, it should include before and after code examples. **Validates: Requirements 6.3** ### Property 22: Improvement trade-offs *For any* improvement suggestion, it should include an explanation of trade-offs. **Validates: Requirements 6.5** ### Property 23: Resource URI mapping *For any* valid resource URI, the system should return the corresponding best practice content. **Validates: Requirements 7.1** ### Property 24: General resource routing *For any* general topic resource URI (bestpractices://general/*), content should come from the general_coding category. **Validates: Requirements 7.2** ### Property 25: FastAPI resource routing *For any* FastAPI topic resource URI (bestpractices://fastapi/*), content should come from the fastapi_specific category. **Validates: Requirements 7.3** ### Property 26: Complete guide resource *For any* request to bestpractices://all, the system should return the complete best practices guide. **Validates: Requirements 7.4** ### Property 27: Invalid resource error handling *For any* invalid resource URI, the system should return an error with suggested valid URIs. **Validates: Requirements 7.5** ### Property 28: JSON validation before processing *For any* database read, the system should validate JSON structure before processing, returning validation errors for invalid JSON rather than processing errors. **Validates: Requirements 9.5** ### Property 29: Invalid parameter error messages *For any* invalid tool parameter, the system should return a descriptive error message with the expected format. **Validates: Requirements 10.1** ### Property 30: Exception safety *For any* unexpected exception, the system should catch it and return a generic error without exposing internal details (stack traces, file paths, etc.). **Validates: Requirements 10.3** ### Property 31: Error resolution suggestions *For any* error, the system should include suggestions for resolution when possible. **Validates: Requirements 10.4** ## Error Handling ### Error Categories 1. **Input Validation Errors** - Empty or null parameters - Invalid category/topic names - Malformed code input - Response: Descriptive error with expected format 2. **File System Errors** - Missing JSON file - Permission denied - Corrupted file - Response: User-friendly message with fallback guidance 3. **JSON Parsing Errors** - Invalid JSON syntax - Missing required keys - Type mismatches - Response: Validation error with specific issue 4. **Search/Query Errors** - No results found - Ambiguous queries - Response: Suggestions for similar topics 5. **Runtime Errors** - Unexpected exceptions - Resource constraints - Response: Generic error without internal details ### Error Response Format ```python { "error": { "type": "string", # Error category "message": "string", # User-friendly description "suggestions": ["string"], # Possible resolutions "details": {} # Optional additional context } } ``` ### Fallback Strategies 1. **Database Unavailable**: Provide basic Python/FastAPI guidance from hardcoded fallbacks 2. **Partial Data**: Return available data with warning about incomplete results 3. **Search Failures**: Use fuzzy matching to suggest alternatives 4. **Invalid Input**: Provide examples of valid input formats ## Testing Strategy ### Unit Testing **Framework**: pytest **Test Coverage**: - Data Manager functions (load, search, query) - Tool input validation - Resource URI parsing - Error handling paths - JSON validation logic **Example Tests**: ```python def test_load_best_practices_valid_file(): """Test loading valid JSON file""" data = load_best_practices() assert "python_best_practices" in data assert "general_coding" in data["python_best_practices"] def test_search_practices_returns_matches(): """Test search returns relevant results""" results = search_practices("async") assert len(results) > 0 assert all("async" in str(r).lower() for r in results) def test_invalid_category_suggests_alternatives(): """Test invalid category returns suggestions""" result = get_category("invalid_category") assert "error" in result assert "suggestions" in result ``` ### Property-Based Testing **Framework**: Hypothesis (Python property-based testing library) **Configuration**: Minimum 100 iterations per property test **Test Strategy**: - Generate random keywords, categories, and code snippets - Verify properties hold across all generated inputs - Use database fixtures with known structure - Test edge cases (empty strings, special characters, very long inputs) **Property Test Examples**: ```python from hypothesis import given, strategies as st @given(st.text(min_size=1)) def test_search_completeness_property(keyword): """Property 1: All search results contain the keyword""" results = search_practices(keyword) for result in results.get("matches", []): result_text = json.dumps(result).lower() assert keyword.lower() in result_text @given(st.sampled_from(["general_coding", "fastapi_specific", "performance", "code_quality"])) def test_category_completeness_property(category): """Property 5: Category requests return all topics""" result = get_category(category) db_data = load_best_practices() expected_topics = set(db_data["python_best_practices"][category].keys()) returned_topics = set(t["name"] for t in result["topics"]) assert expected_topics == returned_topics ``` ### Integration Testing **Test Scenarios**: 1. End-to-end tool invocation through MCP protocol 2. Resource access via URI 3. Prompt execution flow 4. Dynamic file reloading 5. Error handling across all tools **Example Integration Test**: ```python def test_dynamic_reload_integration(): """Test that file changes are reflected in subsequent requests""" # Make initial request initial = list_categories() # Modify JSON file modify_test_database() # Make second request updated = list_categories() # Verify changes reflected assert initial != updated ``` ### Manual Testing Checklist - [ ] Test with Kiro IDE MCP client - [ ] Verify all tools appear in tool list - [ ] Test each prompt template - [ ] Verify resource URIs resolve correctly - [ ] Test with various code samples - [ ] Verify error messages are user-friendly - [ ] Test file modification and reload - [ ] Verify performance with large code inputs ## Performance Considerations ### File I/O Optimization - **Strategy**: Read file on each request (requirement), but optimize parsing - **Caching**: No caching of file content (dynamic reload requirement) - **Optimization**: Use efficient JSON parsing library (orjson if available) ### Search Performance - **Strategy**: In-memory search after loading JSON - **Optimization**: Build search index on load for faster keyword matching - **Complexity**: O(n) where n is number of topics ### Response Size Management - **Strategy**: Limit example code length in responses - **Truncation**: Truncate very long examples with "..." indicator - **Pagination**: Not required for MVP, but consider for future ## Security Considerations 1. **File Path Validation**: Ensure JSON file path is validated and restricted 2. **Input Sanitization**: Sanitize all user inputs to prevent injection 3. **Error Message Safety**: Never expose file paths or internal structure in errors 4. **Code Execution**: Never execute user-provided code, only analyze it 5. **Resource Limits**: Implement reasonable limits on input sizes ## Deployment ### Requirements - Python 3.9+ - FastMCP library - JSON file accessible at relative path: `data/python_best_practices.json` ### Installation ```bash pip install fastmcp ``` ### Running the Server ```bash python bestpractices_mcp_server.py ``` ### Configuration Environment variables: - `BEST_PRACTICES_FILE`: Path to JSON file (default: `data/python_best_practices.json`) - `LOG_LEVEL`: Logging level (default: `INFO`) ## Future Enhancements 1. **Multi-language Support**: Extend to other programming languages 2. **Custom Best Practices**: Allow users to add their own practices 3. **Practice Versioning**: Track changes to best practices over time 4. **Analytics**: Track which practices are most frequently accessed 5. **AI-Enhanced Reviews**: Use LLM for deeper code analysis 6. **Practice Voting**: Community voting on practice quality 7. **Integration Examples**: Provide full project examples 8. **Interactive Tutorials**: Step-by-step guides for each practice