192 lines
6.1 KiB
Markdown
192 lines
6.1 KiB
Markdown
---
|
|
name: MCP rules
|
|
description: Rules for FastMCP tools, resources, and prompts
|
|
applyTo: "finn_eiendom/mcp_server.py,finn_eiendom/**/*mcp*.py"
|
|
---
|
|
|
|
# MCP server rules
|
|
|
|
The MCP server is a **thin wrapper** over `service.py`. It owns:
|
|
|
|
* Tool registration with `@mcp.tool()` and annotations.
|
|
* Pydantic input schemas (these double as tool documentation).
|
|
* Error wrapping at the protocol boundary.
|
|
* JSON / markdown response formatting via `formatting.py`.
|
|
|
|
It does **not** own:
|
|
|
|
* Parsing, scraping, scoring, cache, or HTTP fetching logic.
|
|
* SQLite or `httpx` access.
|
|
* Any orchestration of "check cache, else fetch, else save" — that's `service.py`.
|
|
|
|
## Server bootstrap
|
|
|
|
```python
|
|
# finn_eiendom/mcp_server.py
|
|
import sys, logging
|
|
from mcp.server.fastmcp import FastMCP
|
|
|
|
logging.basicConfig(stream=sys.stderr, level=logging.INFO,
|
|
format="%(asctime)s %(levelname)s %(name)s %(message)s")
|
|
|
|
mcp = FastMCP("finn_eiendom_mcp")
|
|
|
|
# ... tools registered here ...
|
|
|
|
def main() -> None:
|
|
mcp.run(transport="stdio")
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
```
|
|
|
|
stdio servers **must** log to stderr only — anything on stdout breaks the JSON-RPC frame.
|
|
|
|
## Tool naming
|
|
|
|
All tools use the `finn_` prefix so they don't collide with other MCP servers running in the same Claude Desktop:
|
|
|
|
* `finn_analyze_search`
|
|
* `finn_get_ad`
|
|
* `finn_compare_ads`
|
|
* `finn_save_feedback`
|
|
* `finn_get_shortlist`
|
|
* `finn_get_new_ads_since_last_run`
|
|
* `finn_resolve_eiendom_unit`
|
|
* `finn_get_eiendom_unit`
|
|
* `finn_enrich_ad`
|
|
* `finn_build_unit_vector`
|
|
* `finn_decode_unit_vector`
|
|
* `finn_get_similar_units`
|
|
* `finn_find_similar_to_liked_ad`
|
|
* `finn_analyze_ad_against_comps`
|
|
|
|
## Tool body shape
|
|
|
|
Every tool body looks like this:
|
|
|
|
```python
|
|
@mcp.tool(
|
|
annotations=ToolAnnotations(
|
|
title="Analyze a FINN search URL",
|
|
readOnlyHint=True,
|
|
destructiveHint=False,
|
|
openWorldHint=True,
|
|
)
|
|
)
|
|
async def finn_analyze_search(input: AnalyzeSearchInput) -> str:
|
|
"""Analyze a FINN search URL and return a ranked shortlist."""
|
|
try:
|
|
result = await service.analyze_search(
|
|
search_url=input.search_url,
|
|
max_pages=input.max_pages,
|
|
detail_limit=input.detail_limit,
|
|
include_details=input.include_details,
|
|
include_eiendom_no=input.include_eiendom_no,
|
|
include_similar_units_for_shortlist=input.include_similar_units_for_shortlist,
|
|
)
|
|
return formatting.render_shortlist(result, input.response_format)
|
|
except Exception as e:
|
|
log.exception("finn_analyze_search failed")
|
|
return json.dumps({
|
|
"error": True,
|
|
"code": type(e).__name__,
|
|
"message": str(e),
|
|
})
|
|
```
|
|
|
|
Notes:
|
|
|
|
* Every tool delegates to `service.<function>` in one call.
|
|
* Every tool wraps in try/except and returns the error envelope as a JSON string.
|
|
* Output rendering goes through `formatting.py`, never inline.
|
|
* If the tool body needs more than ~20 lines, logic has leaked out of the service layer — push it back down.
|
|
|
|
## Input schemas
|
|
|
|
Every tool has a Pydantic v2 input model. Schemas live with the tool in `mcp_server.py` (they document the tool to LLM clients). Reuse from `models.py` only when the same shape is also a domain object — otherwise keep them as tool-local input types.
|
|
|
|
```python
|
|
class AnalyzeSearchInput(BaseModel):
|
|
search_url: str = Field(..., description="Full FINN search URL")
|
|
max_pages: int = Field(default=3, ge=1, le=10)
|
|
detail_limit: int = Field(default=20, ge=1, le=100)
|
|
include_details: bool = True
|
|
include_eiendom_no: bool = True
|
|
include_similar_units_for_shortlist: bool = False
|
|
response_format: Literal["json", "markdown"] = "json"
|
|
```
|
|
|
|
## Annotations
|
|
|
|
Set the right hints:
|
|
|
|
* Read-only tools (most of them): `readOnlyHint=True, destructiveHint=False, openWorldHint=True`.
|
|
* `finn_save_feedback`: `readOnlyHint=False, destructiveHint=False, idempotentHint=False`.
|
|
|
|
## Response format
|
|
|
|
Tools accept a `response_format` parameter (`"json"` or `"markdown"`):
|
|
|
|
* `"json"` — return `json.dumps(result_dict)`.
|
|
* `"markdown"` — return `formatting.render_<thing>(result, "markdown")`.
|
|
|
|
Errors are always returned as the JSON error envelope regardless of `response_format`.
|
|
|
|
## What stays out of mcp_server.py
|
|
|
|
* `import httpx` — never.
|
|
* `import sqlite3` — never.
|
|
* `from .ad import ...`, `from .search import ...`, `from .eiendom_no import ...`, `from .scoring import ...`, `from .cache import ...`, `from .http import ...` — never. Go through `service`.
|
|
* Output formatting logic — goes in `formatting.py`.
|
|
* Cache management — goes in `service.py`.
|
|
|
|
Allowed imports in `mcp_server.py`:
|
|
|
|
```python
|
|
import json, logging, sys
|
|
from typing import Literal, Optional
|
|
from mcp.server.fastmcp import FastMCP
|
|
from mcp.server.fastmcp.utilities import ToolAnnotations
|
|
from pydantic import BaseModel, Field
|
|
from . import service, formatting
|
|
from .models import FinnAd, EiendomUnit, SimilarUnit # only if needed for type hints
|
|
from . import config
|
|
```
|
|
|
|
`tests/test_architecture.py` enforces this.
|
|
|
|
## Resources and prompts
|
|
|
|
When you add resources or prompts, they follow the same rule: thin wrappers over `service.py` and `formatting.py`. Resources:
|
|
|
|
```
|
|
finn://preferences/current
|
|
finn://search-runs/latest
|
|
finn://search-runs/{id}
|
|
finn://ads/{finnkode}
|
|
finn://ads/{finnkode}/enriched
|
|
finn://shortlist/latest
|
|
finn://feedback/{finnkode}
|
|
finn://eiendom-units/{unitCode}
|
|
finn://eiendom-units/{unitCode}/similar/{listingStatus}
|
|
```
|
|
|
|
Prompts: `evaluate_property_for_user`, `compare_properties_for_user`, `refine_search_from_feedback`, `find_more_like_this`.
|
|
|
|
## When uncertain about FastMCP
|
|
|
|
Use `context7` for FastMCP / MCP SDK questions instead of guessing:
|
|
|
|
```
|
|
context7:resolve-library-id → "modelcontextprotocol/python-sdk" or similar
|
|
context7:query-docs(id, "FastMCP tool annotations") → snippets
|
|
```
|
|
|
|
See `docs.instructions.md`.
|
|
|
|
## Transports
|
|
|
|
* Default: stdio. `finn-eiendom-mcp` is the entry point.
|
|
* Optional: Streamable HTTP via `finn-eiendom serve --transport http --port 8010`. Path: `POST /mcp`. Operational endpoints: `GET /health`, `GET /version`, `GET /debug/config`.
|
|
* Keep tools transport-agnostic. No request/response shape depends on the transport. |