Best Practices MCP Server

# Requirements Document ## Introduction This document specifies the requirements for a Model Context Protocol (MCP) server that provides Python coding best practices and guidelines for general coding and API development. The server will help AI assistants provide better coding guidance to developers by offering interactive tools for searching and retrieving coding standards from a JSON-based knowledge base. ## Glossary - **MCP Server**: A Model Context Protocol server that exposes tools, resources, and prompts to AI assistants - **Best Practices Database**: The JSON file (python_best_practices.json) containing coding standards and examples - **Tool**: An MCP-exposed function that AI assistants can invoke - **Resource**: An MCP-exposed data endpoint accessible via URI - **Prompt**: A pre-built template that AI assistants can use for common tasks - **Category**: A top-level grouping of best practices (e.g., general_coding, fastapi_specific) - **Topic**: A specific subject within a category (e.g., error_handling, pydantic_models) ## Requirements ### Requirement 1 **User Story:** As a developer using an AI assistant, I want to search for best practices by keyword, so that I can quickly find relevant coding guidelines. #### Acceptance Criteria 1. WHEN a user searches with a keyword THEN the system SHALL return all matching best practices containing that keyword in their description, examples, or topic names 2. WHEN a search returns results THEN the system SHALL include the description, concise examples, and related practices for each match 3. WHEN a search returns no exact matches THEN the system SHALL suggest similar topics based on keyword similarity 4. WHEN multiple matches are found THEN the system SHALL organize results by category and relevance 5. WHEN a search keyword is empty or invalid THEN the system SHALL return an error message with guidance ### Requirement 2 **User Story:** As a developer, I want to retrieve best practices by category, so that I can explore all guidelines for a specific area of development. #### Acceptance Criteria 1. WHEN a user requests a specific category THEN the system SHALL return all topics and their details within that category 2. WHEN a category request is made THEN the system SHALL include descriptions, examples, and documentation links for each topic 3. WHEN an invalid category is requested THEN the system SHALL suggest valid categories based on similarity 4. WHEN a category is retrieved THEN the system SHALL format the response in a structured, readable manner 5. WHEN a category contains nested topics THEN the system SHALL preserve the hierarchical structure in the response ### Requirement 3 **User Story:** As a developer, I want to list all available categories, so that I can understand what best practices are available. #### Acceptance Criteria 1. WHEN a user requests the category list THEN the system SHALL return all top-level categories from the Best Practices Database 2. WHEN listing categories THEN the system SHALL include a brief description of each category's focus area 3. WHEN listing categories THEN the system SHALL include the count of topics within each category 4. WHEN the Best Practices Database is updated THEN the system SHALL reflect changes in the next category list request 5. WHEN categories are listed THEN the system SHALL organize them in a logical order ### Requirement 4 **User Story:** As a developer, I want to get code examples for specific topics, so that I can see practical implementations of best practices. #### Acceptance Criteria 1. WHEN a user requests examples for a topic THEN the system SHALL return all code examples associated with that topic 2. WHEN examples are returned THEN the system SHALL include context and explanations for each example 3. WHEN a topic has no examples THEN the system SHALL suggest related topics that have examples 4. WHEN examples are provided THEN the system SHALL format code with proper syntax highlighting markers 5. WHEN multiple examples exist THEN the system SHALL organize them from basic to advanced ### Requirement 5 **User Story:** As a developer, I want the AI assistant to review my code against best practices, so that I can identify areas for improvement. #### Acceptance Criteria 1. WHEN a user provides code for review THEN the system SHALL analyze the code against relevant best practices from the database 2. WHEN reviewing code THEN the system SHALL identify violations of best practices and provide specific recommendations 3. WHEN reviewing code THEN the system SHALL detect the code context (general Python vs FastAPI) and apply appropriate guidelines 4. WHEN code follows best practices THEN the system SHALL acknowledge good patterns and suggest advanced improvements 5. WHEN code review is requested THEN the system SHALL provide actionable feedback with example corrections ### Requirement 6 **User Story:** As a developer, I want specific improvement suggestions for my code, so that I can make targeted enhancements. #### Acceptance Criteria 1. WHEN a user requests improvement suggestions THEN the system SHALL provide concrete code modifications based on best practices 2. WHEN suggesting improvements THEN the system SHALL prioritize changes by impact (critical, important, nice-to-have) 3. WHEN suggesting improvements THEN the system SHALL include before/after code examples 4. WHEN code is already optimal THEN the system SHALL confirm this and suggest alternative patterns if applicable 5. WHEN multiple improvements are possible THEN the system SHALL explain the trade-offs of each approach ### Requirement 7 **User Story:** As a developer, I want to access best practices through MCP resources, so that AI assistants can reference them directly in conversations. #### Acceptance Criteria 1. WHEN an AI assistant requests a resource URI THEN the system SHALL return the corresponding best practice content 2. WHEN a general topic resource is requested THEN the system SHALL return content from the general_coding category 3. WHEN a FastAPI topic resource is requested THEN the system SHALL return content from the fastapi_specific category 4. WHEN the all-practices resource is requested THEN the system SHALL return the complete best practices guide 5. WHEN an invalid resource URI is requested THEN the system SHALL return an error with suggested valid URIs ### Requirement 8 **User Story:** As a developer, I want pre-built prompts for common tasks, so that I can quickly request code reviews and suggestions. #### Acceptance Criteria 1. WHEN an AI assistant lists available prompts THEN the system SHALL expose prompts for code review, FastAPI review, improvement suggestions, and example retrieval 2. WHEN a code review prompt is invoked THEN the system SHALL request the user's code and perform a comprehensive review 3. WHEN a FastAPI review prompt is invoked THEN the system SHALL focus on FastAPI-specific best practices 4. WHEN an improvement prompt is invoked THEN the system SHALL provide prioritized, actionable suggestions 5. WHEN an example prompt is invoked THEN the system SHALL request a topic and return relevant examples ### Requirement 9 **User Story:** As a developer, I want the server to read the best practices file dynamically, so that updates to the knowledge base are reflected without restarting the server. #### Acceptance Criteria 1. WHEN a tool is invoked THEN the system SHALL read the Best Practices Database from disk at request time 2. WHEN the Best Practices Database file is updated THEN the system SHALL use the new content in subsequent requests 3. WHEN the Best Practices Database file is missing or corrupted THEN the system SHALL return a clear error message 4. WHEN reading the database fails THEN the system SHALL provide fallback guidance and log the error 5. WHEN the database is read THEN the system SHALL validate the JSON structure before processing ### Requirement 10 **User Story:** As a system administrator, I want the server to handle errors gracefully, so that users receive helpful feedback when issues occur. #### Acceptance Criteria 1. WHEN an invalid tool parameter is provided THEN the system SHALL return a descriptive error message with expected format 2. WHEN a file system error occurs THEN the system SHALL log the error and return a user-friendly message 3. WHEN an unexpected exception occurs THEN the system SHALL catch it and return a generic error without exposing internals 4. WHEN errors occur THEN the system SHALL include suggestions for resolution when possible 5. WHEN the system encounters rate limits or resource constraints THEN the system SHALL communicate this clearly to the user