get_form_details
Retrieve detailed information about specific French tax forms, including required fields and official instructions, to complete tax documentation accurately.
Instructions
Get detailed information about a specific tax form including fields and instructions
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| form_number | Yes | ||
| year | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- french_tax_mcp/server.py:167-300 (handler)Primary MCP tool handler decorated with @mcp.tool. Calls scraper.get_form_info() or provides hardcoded fallback data for common French tax forms (2042, 2044, 2031).
@mcp.tool( name="get_form_details", description="Get detailed information about a specific tax form including fields and instructions", ) async def get_form_details_wrapper(form_number: str, ctx: Context, year: Optional[int] = None) -> Optional[Dict]: """Get detailed information about a specific tax form. Args: form_number: The form number (e.g., '2042', '2044', '2072') year: Tax year (defaults to current year if not specified) ctx: MCP context for logging and state management Returns: Dict: Dictionary containing detailed information about the tax form """ try: # Set default year to current year if not specified if year is None: year = datetime.now().year await ctx.info(f"Retrieving details for form {form_number} for year {year}") # Try to get information from the scraper first try: from french_tax_mcp.scrapers.impots_scraper import get_form_info result = await get_form_info(form_number, year) if result.get("status") == "success": return result except Exception as e: await ctx.warning(f"Failed to get form details from web: {e}. Using fallback data.") # If web scraping fails or returns an error, use fallback data form_number = form_number.strip() # Provide fallback data for common forms if form_number == "2042": return { "status": "success", "message": f"Retrieved fallback information for form 2042 for {year}", "data": { "form": "2042", "year": year, "title": "Déclaration des revenus", "description": "Formulaire principal de déclaration des revenus des personnes physiques.", "sections": [ "État civil et situation de famille", "Traitements, salaires, pensions et rentes", "Revenus de capitaux mobiliers", "Plus-values et gains divers", "Revenus fonciers", "Charges déductibles", "Réductions et crédits d'impôt", ], "deadline": f"31 mai {year} (déclaration en ligne)", "related_forms": [ {"number": "2042-C", "title": "Déclaration complémentaire"}, {"number": "2042-RICI", "title": "Réductions d'impôt et crédits d'impôt"}, {"number": "2044", "title": "Revenus fonciers"}, ], "download_link": "https://www.impots.gouv.fr/formulaire/2042/declaration-des-revenus", }, "source": "Fallback data", } elif form_number == "2044": return { "status": "success", "message": f"Retrieved fallback information for form 2044 for {year}", "data": { "form": "2044", "year": year, "title": "Déclaration des revenus fonciers", "description": "Formulaire de déclaration des revenus fonciers (locations non meublées).", "sections": [ "Propriétés rurales et urbaines", "Recettes brutes", "Frais et charges", "Intérêts d'emprunt", "Détermination du revenu ou déficit", ], "deadline": f"31 mai {year} (avec la déclaration principale)", "related_forms": [ {"number": "2042", "title": "Déclaration des revenus"}, { "number": "2044-SPE", "title": "Déclaration des revenus fonciers spéciaux", }, ], "download_link": "https://www.impots.gouv.fr/formulaire/2044/declaration-des-revenus-fonciers", }, "source": "Fallback data", } elif form_number == "2031": return { "status": "success", "message": f"Retrieved fallback information for form 2031 for {year}", "data": { "form": "2031", "year": year, "title": "Déclaration des résultats BIC", "description": "Formulaire de déclaration des bénéfices industriels et commerciaux (BIC) au régime réel.", "sections": [ "Identification de l'entreprise", "Résultat fiscal", "Immobilisations et amortissements", "Provisions", "Plus-values et moins-values", ], "deadline": f"Début mai {year} (entreprises soumises à l'IR)", "related_forms": [ {"number": "2033-A à G", "title": "Régime simplifié"}, {"number": "2042-C-PRO", "title": "Report des revenus professionnels"}, ], "download_link": "https://www.impots.gouv.fr/formulaire/2031-sd/declaration-de-resultats", }, "source": "Fallback data", } else: # For unknown forms, return a more informative error return { "status": "error", "message": f"Information for form {form_number} not available", "form": form_number, "year": year, "available_forms": ["2042", "2044", "2031"], } except Exception as e: await ctx.error(f"Failed to get form details: {e}") return { "status": "error", "message": f"Error retrieving form details: {str(e)}", "form": form_number, "year": year, } - Core scraping implementation in ImpotsScraper class. Fetches form page from impots.gouv.fr and extracts structured information using BeautifulSoup.
async def get_form_info(self, form_number: str, year: Optional[int] = None) -> Dict: """Scrape information about a specific tax form from impots.gouv.fr. Args: form_number: The form number (e.g., '2042', '2044') year: The tax year. Defaults to current year. Returns: Dictionary containing information about the form """ # Set default year to current year if not specified current_year = datetime.now().year tax_year = year or current_year logger.info(f"Scraping information for form {form_number} for year {tax_year}") try: # Construct URL url = f"{FORMS_BASE_URL}/formulaire-{form_number}.html" # Get the page response = await self.get_page(url) # Parse HTML soup = self.parse_html(response.text) # Extract form information form_info = self._extract_form_info(soup, form_number, tax_year) return self.format_result( status="success", data=form_info, message=f"Successfully retrieved information for form {form_number}", source_url=f"{BASE_URL}{url}", ) except Exception as e: logger.error(f"Error scraping form information: {e}") return self.format_result( status="error", message=f"Failed to retrieve form information: {str(e)}", data={"form": form_number, "year": tax_year}, error=e, ) - Top-level exported helper function imported by server.py handler, proxies to singleton ImpotsScraper instance.
async def get_form_info(form_number: str, year: Optional[int] = None) -> Dict: """Scrape information about a specific tax form from impots.gouv.fr. Args: form_number: The form number (e.g., '2042', '2044') year: The tax year. Defaults to current year. Returns: Dictionary containing information about the form """ return await impots_scraper.get_form_info(form_number, year)