flatin-mcp 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flatin.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# flatin.pt MCP server — buying a home in Portugal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server for the questions people ask before buying a home in Portugal: **which new-build developments fit a budget**, **where to live in a city, area by area**, **what a municipality looks like in numbers**, and **what the purchase and the yearly property tax cost** — with the flatin.pt page link and the source of every number.
+
+It is run by [flatin.pt](https://flatin.pt/en/) and listed in the official MCP Registry as [`pt.flatin/property-taxes`](https://registry.modelcontextprotocol.io/v0.1/servers/pt.flatin%2Fproperty-taxes/versions/latest) (the name predates the wider scope; version 2.1.0 covers new-builds and places and publishes an output schema for every tool).
+
+```
+You:    T2 new-builds in Vila Nova de Gaia under 400 000 €? And what would I pay on top?
+
+Claude: [search_newbuilds municipality="Vila Nova de Gaia" typology="T2" price_max=400000]
+        [imt_calculate value="380000"]
+        Lists the matching projects with their price per typology, stage,
+        delivery date and flatin.pt page; then IMT, stamp duty and the
+        registration on top of the price, with the Autoridade Tributária
+        tables as the source.
+```
+
+## Tools
+
+| Tool | What it answers |
+|---|---|
+| `imt_calculate` | What a purchase costs on top of the price: IMT (transfer tax), Imposto do Selo (stamp duty) and the published price of the property registration (Casa Pronta). Official 2026 tables, including the reduced IMT table and the stamp duty deduction for buyers aged 35 or under. Both taxes are charged on the higher of the contract price and the VPT: pass `vpt` when it is known. |
+| `imi_rate` | The yearly property tax (IMI) rate of one municipality, by name or four-digit code, with its history since 2023. Where a municipality sets no single rate (it is set per parish), the answer says so instead of returning zero. |
+| `imi_annual_cost` | Yearly IMI for an urban property with a given taxable value (VPT). VPT is the tax authority's valuation, not the purchase price. |
+| `request_consultation` | Sends the person's request to a licensed real estate agency (AMI), in two steps: `mode=prepare` checks the details and returns a summary, the GDPR consent text in their language and a confirmation token; `mode=submit` sends it only with that token, `consent=true` and the text version, after the person has read the text and agreed. `mode=link` (default) returns just the form link. |
+| `subscribe_digest` | Subscribes the person's email to new-build developments matching a filter (daily) or to newly licensed construction in a municipality (weekly). It only sends a confirmation email: nothing is active until they click the link. |
+| `where_to_live` | Where to live in a Portuguese city or region, area by area: the verdict of a flatin.pt guide (live, depends, avoid) with the reason, who each area suits, noise in plain words and dated, sourced safety notes. Without `city`, the list of guides. |
+| `municipality_stats` | Key figures for one of the 308 municipalities: IMI rate and history, INE median sale price per m², purchasing power, population, licensed buildings and dwellings, construction activity, new-builds in the catalogue — each with source and date. |
+| `compare_municipalities` | The same figures for two to five municipalities side by side. |
+| `construction_barometer` | Construction activity: monthly municipal building-works cases where we collect them, plus INE's yearly licensed buildings and new dwellings for any municipality. |
+| `glossary_lookup` | A Portuguese home-buying or tax term (CPCV, escritura, caderneta predial, VPT…) explained, with the article of law and the date it was checked. |
+| `search_newbuilds` | New-build housing projects on flatin.pt by municipality, parish, typology (T0–T5), budget, stage, delivery year and energy class: price per typology, stage, delivery date, developer, coordinates and the project page link. |
+| `get_newbuild` | One new-build project: units and prices per typology with price history, delivery promises, building permits, the purchase cost (IMT, stamp duty, registration) and what is nearby, with the page link in seven languages. |
+
+Every successful answer carries an `attribution` field — who computed it, from which table and year, and a link to the primary source — and, where there is one, the canonical flatin.pt page URL. Please show both to the user: numbers without a source cannot be checked.
+
+The two write tools (`request_consultation`, `subscribe_digest`) act only with the person's explicit consent: `prepare` returns the consent text and a token and sends nothing; `submit` needs that token and `consent=true`. Municipalities can be named in Portuguese or English (Lisboa or Lisbon), by slug or by four-digit code.
+
+## Connect
+
+The server is **remote** — nothing to install. Point your client at:
+
+```
+https://flatin.pt/mcp
+```
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http flatin https://flatin.pt/mcp
+```
+
+**Clients that can only start a local process** (stdio) — use the bridge in this repository. It needs Node.js 18.17 or newer and has no dependencies:
+
+```bash
+claude mcp add flatin -- npx -y gitlab:flatin-pt-group/mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "flatin": {
+      "command": "npx",
+      "args": ["-y", "gitlab:flatin-pt-group/mcp"]
+    }
+  }
+}
+```
+
+The bridge forwards each JSON-RPC message to `https://flatin.pt/mcp` and writes the answer back. It stores nothing and sends nothing except what your client sends. Set `FLATIN_MCP_URL` to point it elsewhere.
+
+**Docker**
+
+```bash
+docker build -t flatin-mcp . && docker run -i --rm flatin-mcp
+```
+
+## The data behind it
+
+- **New-build developments**: prices per typology and delivery dates as published by developers, with the date they were checked, and building permits from municipal open-data portals — [catalogue](https://flatin.pt/en/new-developments/).
+- **Where to live**: flatin.pt city guides area by area, and municipality figures from INE (median sale price per m², purchasing power, population, licensed construction).
+- **IMI rates, all 308 municipalities**, checked line by line against the Autoridade Tributária portal — [open data page](https://flatin.pt/en/tools/imi-open-data/), [CSV](https://flatin.pt/api/v1/imi/rates.csv), licence CC BY 4.0.
+- **IMT and stamp duty** from the official 2026 tables — the same numbers as the [IMT calculator](https://flatin.pt/en/tools/imt-calculator/).
+- **REST API** with the same functions: [API and data](https://flatin.pt/en/tools/api-and-data/) · [OpenAPI schema](https://flatin.pt/api/openapi.json).
+
+The MCP server, the API and the website call the same code, so the three never disagree by a cent.
+
+## Guides
+
+- [Buying property in Portugal: costs and taxes](https://flatin.pt/en/guides/buying-property-portugal-costs-taxes/)
+- [NIF and residency for foreign buyers](https://flatin.pt/en/guides/nif-residency-foreign-buyers/)
+- In Portuguese: [Comprar casa: custos e impostos](https://flatin.pt/pt/guias/comprar-casa-custos-impostos/) · [Calculadora de IMT](https://flatin.pt/pt/ferramentas/calculadora-imt/)
+
+## Development
+
+```bash
+node --test
+```
+
+This repository is published from the flatin.pt codebase; issues and suggestions are welcome here.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). The data returned by the server is licensed separately under CC BY 4.0.

package/bin/flatin-mcp.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/*
+ * flatin-mcp — a stdio bridge to the flatin.pt MCP server.
+ *
+ * The server itself is remote (https://flatin.pt/mcp, streamable HTTP) and
+ * stateless. Some MCP clients can only start a local process and talk to it
+ * over stdin/stdout; this bridge is that process. It forwards every JSON-RPC
+ * message unchanged and writes the answer back. It adds nothing, stores
+ * nothing and sends nothing except what the client sent.
+ *
+ * Rules the bridge keeps:
+ *   - stdout carries JSON-RPC only, one message per line; diagnostics go to stderr;
+ *   - a notification (no id) never produces output;
+ *   - every request with an id gets exactly one answer, even when the network,
+ *     a proxy or the server fails — a client must never wait forever;
+ *   - the protocol version is forwarded: the one negotiated in `initialize`,
+ *     or the one a client states in a request's `_meta`.
+ */
+'use strict';
+
+const readline = require('node:readline');
+const { version: VERSION } = require('../package.json');
+
+const ENDPOINT = process.env.FLATIN_MCP_URL || 'https://flatin.pt/mcp';
+const TIMEOUT_MS = Number(process.env.FLATIN_MCP_TIMEOUT_MS || 30000);
+
+const PARSE_ERROR = -32700;
+const INTERNAL_ERROR = -32603;
+
+let negotiatedVersion = null;
+
+function log(message) {
+  process.stderr.write(`[flatin-mcp] ${message}\n`);
+}
+
+function emit(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasId(message) {
+  return isObject(message) && message.id !== undefined && message.id !== null;
+}
+
+function isJsonRpc(message) {
+  return isObject(message) && message.jsonrpc === '2.0';
+}
+
+function errorReply(id, code, text) {
+  return { jsonrpc: '2.0', id, error: { code, message: text } };
+}
+
+/** The requests in a message that are owed an answer. */
+function idsOf(request) {
+  return (Array.isArray(request) ? request : [request]).filter(hasId).map((item) => item.id);
+}
+
+/** A version the client states itself, e.g. in `params._meta`, when there was no handshake. */
+function statedVersion(request) {
+  for (const item of Array.isArray(request) ? request : [request]) {
+    const meta = isObject(item) && isObject(item.params) && isObject(item.params._meta) ? item.params._meta : null;
+    if (!meta) continue;
+    for (const [key, value] of Object.entries(meta)) {
+      if (/protocolversion$/i.test(key) && typeof value === 'string') return value;
+    }
+  }
+  return null;
+}
+
+/** Split a server-sent events body into the JSON-RPC messages it carries. */
+function parseEvents(text) {
+  const messages = [];
+  let data = [];
+  const flush = () => {
+    if (data.length) messages.push(JSON.parse(data.join('\n')));
+    data = [];
+  };
+  for (const line of text.split(/\r?\n/)) {
+    if (line === '') flush();
+    else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+  }
+  flush();
+  return messages;
+}
+
+async function post(request) {
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+    'User-Agent': `flatin-mcp/${VERSION} (+https://gitlab.com/flatin-pt-group/mcp)`,
+  };
+  const version = negotiatedVersion || statedVersion(request);
+  if (version) headers['MCP-Protocol-Version'] = version;
+
+  const response = await fetch(ENDPOINT, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(request),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  const text = await response.text();
+  if (response.status === 202 && !text) return { status: 202, messages: [] };
+
+  let messages;
+  try {
+    if ((response.headers.get('content-type') || '').includes('text/event-stream')) {
+      messages = parseEvents(text);
+    } else if (text) {
+      // A batch answer stays one message: it goes back to the client as a batch.
+      messages = [JSON.parse(text)];
+    } else {
+      messages = [];
+    }
+  } catch {
+    throw new Error(`HTTP ${response.status}: the answer is not JSON`);
+  }
+  return { status: response.status, messages };
+}
+
+/**
+ * Turn what the server sent into what the client is owed.
+ *
+ * - A JSON-RPC answer passes through. If the server could not read the id
+ *   (a refusal with `id: null` or no id), the bridge did read it and puts it
+ *   back — for every id in a batch.
+ * - Anything that is not JSON-RPC (a proxy page, `{"detail": ...}`, an HTTP
+ *   error body) becomes a JSON-RPC error for each waiting id.
+ */
+function answersFor(request, status, messages) {
+  const waiting = idsOf(request);
+  const out = [];
+  for (const message of messages) {
+    if (Array.isArray(message)) {
+      const items = message.filter(isJsonRpc);
+      if (items.length) out.push(items);
+      continue;
+    }
+    if (!isJsonRpc(message)) {
+      const detail = isObject(message) && (message.message || message.detail || message.error);
+      const text = `HTTP ${status}: ${typeof detail === 'string' ? detail : 'not a JSON-RPC answer'}`;
+      for (const id of waiting) out.push(errorReply(id, INTERNAL_ERROR, text));
+      continue;
+    }
+    if ((message.id === null || message.id === undefined) && message.error && waiting.length) {
+      for (const id of waiting) out.push({ ...message, id });
+      continue;
+    }
+    out.push(message);
+  }
+  return out;
+}
+
+function rememberVersion(request, answers) {
+  const requests = Array.isArray(request) ? request : [request];
+  const flat = answers.flatMap((answer) => (Array.isArray(answer) ? answer : [answer]));
+  for (const item of requests) {
+    if (!isObject(item) || item.method !== 'initialize') continue;
+    const answer = flat.find((a) => isObject(a) && a.id === item.id);
+    if (answer && answer.result && answer.result.protocolVersion) {
+      negotiatedVersion = answer.result.protocolVersion;
+    }
+  }
+}
+
+async function handle(line) {
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch {
+    emit(errorReply(null, PARSE_ERROR, 'the message is not valid JSON'));
+    return;
+  }
+  const waiting = idsOf(request);
+  try {
+    const { status, messages } = await post(request);
+    const answers = answersFor(request, status, messages);
+    rememberVersion(request, answers);
+    for (const answer of answers) emit(answer);
+    const answered = new Set(
+      answers.flatMap((a) => (Array.isArray(a) ? a : [a])).filter(hasId).map((a) => a.id),
+    );
+    const missing = waiting.filter((id) => !answered.has(id));
+    if (missing.length && status !== 202) {
+      for (const id of missing) emit(errorReply(id, INTERNAL_ERROR, `HTTP ${status}: no answer for this request`));
+    }
+  } catch (error) {
+    const reason = error && error.name === 'TimeoutError' ? `no answer within ${TIMEOUT_MS} ms` : String(error && error.message);
+    log(`request failed: ${reason}`);
+    for (const id of waiting) emit(errorReply(id, INTERNAL_ERROR, `flatin.pt MCP server is unreachable: ${reason}`));
+  }
+}
+
+function main() {
+  const pending = new Set();
+  const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  input.on('line', (line) => {
+    if (!line.trim()) return;
+    const job = handle(line).finally(() => pending.delete(job));
+    pending.add(job);
+  });
+  // No process.exit(): on macOS stdout to a pipe is asynchronous, and exiting
+  // right after the last write can cut a large answer. The process ends by
+  // itself once stdin is closed and every request has been answered.
+  input.on('close', () => {
+    Promise.allSettled([...pending]).then(() => {
+      process.exitCode = 0;
+    });
+  });
+  log(`bridging stdio to ${ENDPOINT}`);
+}
+
+main();

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "flatin-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "MCP stdio bridge to flatin.pt: buying a home in Portugal — new-build search, where-to-live guides, municipality data, IMT and IMI taxes.",
+  "mcpName": "pt.flatin/property-taxes",
+  "bin": {
+    "flatin-mcp": "bin/flatin-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "portugal",
+    "property-tax",
+    "imi",
+    "imt",
+    "real-estate",
+    "new-build",
+    "open-data"
+  ],
+  "homepage": "https://flatin.pt/en/tools/api-and-data/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/flatin-pt-group/mcp.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/flatin-pt-group/mcp/-/issues"
+  },
+  "author": "flatin.pt (https://flatin.pt)",
+  "license": "MIT"
+}