feat: Add .tool-versions file, remove unused Docker documentation, and create repository summary and story files; enhance analysis.py and add fetch_trikk_coords.py script

2026-06-10 13:03:08 +02:00
parent eb95b98111
commit 793dd2c3a9
9 changed files with 82 additions and 575 deletions
@@ -0,0 +1,43 @@
+# Repository Analysis: finn-eiendom-mcp
+
+## Overview
+`finn-eiendom-mcp` is a private, self-hosted real estate analysis platform. It automates the process of scouring FINN real estate listings, enriching the data with external information from Eiendom.no (such as unit values and comparable sales), scoring the properties based on user preferences, and caching results for efficiency. It is designed as a high-precision decision-support tool for personal home searching.
+
+## Architecture
+The project follows a strictly layered service-oriented architecture to ensure logic is centralized and reusable across multiple entry points.
+
+- **Service Layer (`service.py`)**: The core engine. Orchestrates data fetching, caching, and analysis. It is the "single source of truth" for business logic.
+- **Domain Logic (`analysis.py`, `scoring.py`, `eiendom_no.py`, `ad.py`, `search.py`)**: Handles specific domain tasks like scraping, enrichment, and scoring.
+- **Persistence (`cache.py`)**: Manages a local SQLite database to store scraped data and analysis results, reducing network overhead and avoiding rate limits.
+- **Entry Points**:
+    - **MCP Server (`mcp_server.py`)**: Provides tools for AI agents (like Claude Desktop) via stdio or HTTP.
+    - **CLI (`cli.py`)**: A Typer-based command-line interface for terminal users and scripting.
+    - **Python Library (`finn_eiendom`)**: A distributable package for programmatic use in notebooks or other applications.
+- **Formatting (`formatting.py`)**: A shared utility for rendering data as JSON, Markdown, or Tables across CLI and MCP.
+
+## Key Components
+- **FINN Scraper**: Parses HTML from FINN search results and specific property advertisements.
+- **Eiendom.no Enricher**: Fetches market data, unit details, and comparable properties to provide context to listings.
+- **Scoring Engine**: A multi-factor model that evaluates properties against user-defined criteria (space, location, price, etc.).
+- **Cache Manager**: A hash-aware SQLite backend that ensures data freshness while respecting provider rate limits.
+
+## Technologies Used
+- **Language**: Python 3.12+
+- **Data Validation**: Pydantic v2
+- **CLI Framework**: Typer
+- **MCP Protocol**: FastMCP
+- **HTTP Client**: `httpx` (async)
+- **HTML Parsing**: `BeautifulSoup4`
+- **Database**: `sqlite3`
+- **Serialization**: `msgpack`
+
+## Data Flow
+1. **Input**: A FINN search URL is provided via CLI or MCP tool.
+2. **Fetch/Cache**: `service.py` checks `cache.py` for existing data. If missing, `http.py` fetches HTML.
+3. **Parsing**: `search.py` and `ad.py` transform HTML into Pydantic models.
+4. **Enrichment**: `eiendom_no.py` fetches supplementary data for the parsed properties.
+5. **Analysis**: `analysis.py` assembles the data; `scoring.py` applies the scoring model.
+6. **Output**: The resulting shortlist is formatted by `formatting.py` into the requested format (Markdown/JSON/Table).
+
+## Team and Ownership
+The repository is maintained by a single developer focused on high-accuracy, low-frequency personal real estate intelligence.