cfpb-complaints-analysis 0.1.0__tar.gz

cfpb_complaints_analysis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Novarini
+
+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.

cfpb_complaints_analysis-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: cfpb-complaints-analysis
+Version: 0.1.0
+Summary: CFPB Consumer Complaint Database as clean Parquet plus an MCP server: 18M complaints and 3.85M archived narratives
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=1.0
+Requires-Dist: mcp<2,>=1.2
+Dynamic: license-file
+
+# cfpb-complaints-analysis
+
+The CFPB Consumer Complaint Database as clean Parquet, plus an MCP server so an AI assistant can query it: 18.2 million complaints (2011 to today) and 3.85 million consumer narratives.
+
+## What is in it
+
+| Layer | Source | Coverage |
+|---|---|---|
+| Structured complaints | CFPB's public complaint file, `files.consumerfinance.gov/ccdb/complaints.csv.zip` | 18,239,728 complaints, received 2011-12-01 to 2026-10-07 (rebuild to refresh) |
+| Narratives | CFPB FOIA Reading Room, "CFPB Consumer Complaint Database Narratives Archive" | 3,851,415 narratives, published through 2026-08-14, none before 2015 |
+
+Both are CFPB's own files. Nothing comes from a third party. CFPB describes the narratives as public domain for FOIA purposes, and says on its data page that complaint data is "freely available for anyone to use, analyze, and build on."
+
+## The narrative freeze
+
+CFPB stopped publishing complaint narratives in September 2026 (database release 24, and the Aug 14, 2026 announcement that it would cease discretionary publication of narratives and visualizations). It moved the previously published narratives to its FOIA Reading Room. The live complaint file has no narrative column any more.
+
+This project joins the archived narratives back to the live complaints by Complaint ID. So:
+
+- Narratives exist only for complaints CFPB had published with one through 2026-08-14. Complaints from after that have none, and it will stay that way.
+- Fewer than half of complaints ever had a narrative: the consumer had to consent, and none were published before 2015.
+- Narratives are scrubbed by CFPB (personal data shows as XXXX).
+- Structured fields keep updating when you rebuild from CFPB's live file.
+
+## Use it
+
+```
+pip install cfpb-complaints-analysis
+cfpb-complaints-mcp
+```
+
+The first run downloads the Parquet files (about 700 MB) from the hosted service to `~/.cache/cfpb-complaints-analysis`. Set `CFPB_DATA_URL` to fetch them from somewhere else, or `CFPB_DATA_DIR` to use a folder you built yourself. Add the server to your MCP client as a stdio command, or use the hosted endpoint listed in the MCP registry as `io.github.bnovarini/cfpb-complaints-analysis`.
+
+Tools: `dataset_info`, `list_values`, `find_company`, `complaint_counts`, `trend`, `company_profile`, `compare_companies`, `search_narratives`, `count_narratives`, `get_complaint`.
+
+Example questions: What do people complain about at Navy Federal versus PenFed? How did mortgage complaints about Rocket change by year? Find 2024 narratives that mention "overdraft fee" at a credit union.
+
+Build it yourself from CFPB's sources: `cfpb-complaints --data data build`.
+
+## Read this before quoting numbers
+
+- Complaints are unverified consumer allegations. CFPB says so itself.
+- Counts are raw. A large company will have more complaints than a small one; nothing is scaled by customers or accounts.
+- CFPB lists some firms under several names. Use `find_company` and `company_contains` to include all variants.
+- The newest months are partial: complaints are still being sent to companies, and "In progress" is a status, not an outcome.
+- Keyword narrative search scans text. Unfiltered searches take about ten seconds. A date, company or product filter makes them much faster.
+
+## Checks
+
+Every count is reconciled to CFPB's own published numbers. See [docs/AUDIT.md](docs/AUDIT.md), including the figures that do not match and why.
+
+## License
+
+MIT for the code. The data is CFPB's.

cfpb_complaints_analysis-0.1.0/README.md

@@ -0,0 +1,54 @@
+# cfpb-complaints-analysis
+
+The CFPB Consumer Complaint Database as clean Parquet, plus an MCP server so an AI assistant can query it: 18.2 million complaints (2011 to today) and 3.85 million consumer narratives.
+
+## What is in it
+
+| Layer | Source | Coverage |
+|---|---|---|
+| Structured complaints | CFPB's public complaint file, `files.consumerfinance.gov/ccdb/complaints.csv.zip` | 18,239,728 complaints, received 2011-12-01 to 2026-10-07 (rebuild to refresh) |
+| Narratives | CFPB FOIA Reading Room, "CFPB Consumer Complaint Database Narratives Archive" | 3,851,415 narratives, published through 2026-08-14, none before 2015 |
+
+Both are CFPB's own files. Nothing comes from a third party. CFPB describes the narratives as public domain for FOIA purposes, and says on its data page that complaint data is "freely available for anyone to use, analyze, and build on."
+
+## The narrative freeze
+
+CFPB stopped publishing complaint narratives in September 2026 (database release 24, and the Aug 14, 2026 announcement that it would cease discretionary publication of narratives and visualizations). It moved the previously published narratives to its FOIA Reading Room. The live complaint file has no narrative column any more.
+
+This project joins the archived narratives back to the live complaints by Complaint ID. So:
+
+- Narratives exist only for complaints CFPB had published with one through 2026-08-14. Complaints from after that have none, and it will stay that way.
+- Fewer than half of complaints ever had a narrative: the consumer had to consent, and none were published before 2015.
+- Narratives are scrubbed by CFPB (personal data shows as XXXX).
+- Structured fields keep updating when you rebuild from CFPB's live file.
+
+## Use it
+
+```
+pip install cfpb-complaints-analysis
+cfpb-complaints-mcp
+```
+
+The first run downloads the Parquet files (about 700 MB) from the hosted service to `~/.cache/cfpb-complaints-analysis`. Set `CFPB_DATA_URL` to fetch them from somewhere else, or `CFPB_DATA_DIR` to use a folder you built yourself. Add the server to your MCP client as a stdio command, or use the hosted endpoint listed in the MCP registry as `io.github.bnovarini/cfpb-complaints-analysis`.
+
+Tools: `dataset_info`, `list_values`, `find_company`, `complaint_counts`, `trend`, `company_profile`, `compare_companies`, `search_narratives`, `count_narratives`, `get_complaint`.
+
+Example questions: What do people complain about at Navy Federal versus PenFed? How did mortgage complaints about Rocket change by year? Find 2024 narratives that mention "overdraft fee" at a credit union.
+
+Build it yourself from CFPB's sources: `cfpb-complaints --data data build`.
+
+## Read this before quoting numbers
+
+- Complaints are unverified consumer allegations. CFPB says so itself.
+- Counts are raw. A large company will have more complaints than a small one; nothing is scaled by customers or accounts.
+- CFPB lists some firms under several names. Use `find_company` and `company_contains` to include all variants.
+- The newest months are partial: complaints are still being sent to companies, and "In progress" is a status, not an outcome.
+- Keyword narrative search scans text. Unfiltered searches take about ten seconds. A date, company or product filter makes them much faster.
+
+## Checks
+
+Every count is reconciled to CFPB's own published numbers. See [docs/AUDIT.md](docs/AUDIT.md), including the figures that do not match and why.
+
+## License
+
+MIT for the code. The data is CFPB's.

cfpb_complaints_analysis-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "cfpb-complaints-analysis"
+version = "0.1.0"
+description = "CFPB Consumer Complaint Database as clean Parquet plus an MCP server: 18M complaints and 3.85M archived narratives"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = ["duckdb>=1.0", "mcp>=1.2,<2"]
+
+[project.scripts]
+cfpb-complaints = "cfpb_complaints.cli:main"
+cfpb-complaints-mcp = "cfpb_complaints.mcp_server:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

cfpb_complaints_analysis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints/build.py

@@ -0,0 +1,78 @@
+"""Build the Parquet files from CFPB's own downloads (live CSV plus the FOIA narratives archive)."""
+from __future__ import annotations
+
+import glob
+import os
+import re
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+import duckdb
+
+LIVE_URL = "https://files.consumerfinance.gov/ccdb/complaints.csv.zip"
+ARCHIVE_PAGE = "https://www.consumerfinance.gov/foia-requests/foia-electronic-reading-room/cfpb-consumer-complaint-database-narratives-archive/"
+UA = {"User-Agent": "cfpb-complaints-analysis (open source research project)"}
+_ZIP = re.compile(r'https://files\.consumerfinance\.gov/f/documents/CCDB_Export_(\d+)_[^"\']*?\.zip')
+
+
+def _get(url: str, dest: Path | None = None) -> bytes | None:
+    req = urllib.request.Request(url, headers=UA)
+    with urllib.request.urlopen(req, timeout=300) as r:
+        if dest is None:
+            return r.read()
+        with open(dest, "wb") as f:
+            while chunk := r.read(1 << 20):
+                f.write(chunk)
+    return None
+
+
+def archive_urls() -> list[tuple[int, str]]:
+    """Scrape the Reading Room page; file names changed over time, so no URL pattern is assumed."""
+    html = _get(ARCHIVE_PAGE).decode("utf-8", "replace")
+    found = {int(m.group(1)): m.group(0) for m in _ZIP.finditer(html)}
+    return sorted(found.items())
+
+
+def _con() -> duckdb.DuckDBPyConnection:
+    c = duckdb.connect()
+    c.execute(f"SET memory_limit='{os.environ.get('CFPB_BUILD_MEMORY', '900MB')}'")
+    c.execute("SET threads=1")
+    c.execute("SET preserve_insertion_order=false")
+    return c
+
+
+def build(data: Path, keep_raw: bool = False) -> None:
+    raw, out = data / "raw", data / "parquet"
+    raw.mkdir(parents=True, exist_ok=True)
+    out.mkdir(parents=True, exist_ok=True)
+    c = _con()
+    z = raw / "complaints.csv.zip"
+    print("downloading live database", file=sys.stderr)
+    _get(LIVE_URL, z)
+    subprocess.run(["unzip", "-q", "-o", str(z), "-d", str(raw)], check=True)
+    csv = raw / "complaints.csv"
+    c.execute(f"""COPY (SELECT cast("Date received" AS DATE) date_received, "Product" product, "Sub-product" sub_product,
+        "Issue" issue, "Sub-issue" sub_issue, "Company public response" company_public_response, "Company" company,
+        "State" state, "ZIP code" zip_code, "Tags" tags, "Submitted via" submitted_via,
+        cast("Date sent to company" AS DATE) date_sent_to_company, "Company response to consumer" company_response,
+        "Timely response?" timely_response, cast("Complaint ID" AS BIGINT) complaint_id
+        FROM read_csv('{csv}', header=true, all_varchar=true, max_line_size=10000000)
+        ORDER BY date_received, complaint_id) TO '{out}/complaints.parquet'
+        (FORMAT PARQUET, COMPRESSION ZSTD, ROW_GROUP_SIZE 100000)""")
+    csv.unlink()
+    for n, url in archive_urls():
+        print(f"narratives archive file {n}", file=sys.stderr)
+        zp = raw / f"archive_{n:02d}.zip"
+        _get(url, zp)
+        subprocess.run(["unzip", "-q", "-o", str(zp), "-d", str(raw / f"a{n:02d}")], check=True)
+        for f in glob.glob(str(raw / f"a{n:02d}" / "*.csv")):
+            c.execute(f"""COPY (SELECT cast("Complaint ID" AS BIGINT) complaint_id, "Consumer complaint narrative" narrative
+                FROM read_csv('{f}', header=true, all_varchar=true, max_line_size=10000000)
+                WHERE trim(coalesce("Consumer complaint narrative", '')) <> '')
+                TO '{out}/narratives_{n:02d}.parquet' (FORMAT PARQUET, COMPRESSION ZSTD, ROW_GROUP_SIZE 20000)""")
+            os.remove(f)
+        if not keep_raw:
+            zp.unlink()
+    print("done:", sorted(p.name for p in out.glob("*.parquet")), file=sys.stderr)

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints/cli.py

@@ -0,0 +1,26 @@
+"""Command line: build the Parquet files from CFPB's sources, or check an existing set."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="cfpb-complaints")
+    ap.add_argument("--data", type=Path, default=Path("data"))
+    ap.add_argument("command", choices=["build", "info"])
+    a = ap.parse_args(argv)
+    if a.command == "build":
+        from .build import build
+        build(a.data)
+    else:
+        import os
+        os.environ["CFPB_DATA_DIR"] = str(a.data / "parquet")
+        from .mcp_server import dataset_info
+        import json
+        print(json.dumps(dataset_info(), indent=2, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints/mcp_server.py

@@ -0,0 +1,447 @@
+"""MCP server over the CFPB Consumer Complaint Database.
+
+Structured data: CFPB's public complaint file (2011 to present, refreshed by rebuilding).
+Narratives: CFPB's FOIA Reading Room archive of narratives published through 2026-08-14.
+CFPB stopped publishing narratives in September 2026, so the narrative layer is frozen at that date.
+DuckDB queries the Parquet files directly.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+import threading
+import time
+import urllib.request
+from datetime import date
+from pathlib import Path
+from typing import Any, Optional
+
+import duckdb
+from mcp.server.fastmcp import FastMCP
+
+RELEASE = "2026-10-07"  # data snapshot; rebuild with `cfpb-complaints build` to refresh
+BASE_URL = os.environ.get("CFPB_DATA_URL", "https://cfpb-complaints-analysis.fly.dev/data/")
+FILES = ["complaints.parquet", *[f"narratives_{i:02d}.parquet" for i in range(1, 22)]]
+MAX_ROWS = 100
+QUERY_TIMEOUT_S = float(os.environ.get("CFPB_QUERY_TIMEOUT", "25"))
+NARRATIVE_FREEZE = "2026-08-14"
+
+NOTE = (
+    "Data: CFPB Consumer Complaint Database (complaints received 2011-12-01 onward, structured fields as CFPB publishes them) "
+    "plus consumer narratives from CFPB's FOIA Reading Room archive. CFPB stopped publishing narratives in September 2026: "
+    "narratives exist only for complaints CFPB had published with a narrative through 2026-08-14 (3.85M of them, none before 2015), so a complaint with no "
+    "narrative may be newer, may lack consumer consent, or may be pre-2015. Complaints are unverified consumer allegations, and a "
+    "company's count is not adjusted for its size. Narratives have personal data masked as XXXX by CFPB."
+)
+mcp = FastMCP("cfpb-complaints-analysis", instructions=NOTE)
+
+_con: Optional[duckdb.DuckDBPyConnection] = None
+
+
+def data_dir() -> Path:
+    env = os.environ.get("CFPB_DATA_DIR")
+    d = Path(env) if env else Path.home() / ".cache" / "cfpb-complaints-analysis" / RELEASE
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def ensure_files() -> Path:
+    d = data_dir()
+    for f in FILES:
+        p = d / f
+        if not p.exists():
+            tmp = p.with_suffix(".part")
+            urllib.request.urlretrieve(BASE_URL + f, tmp)
+            tmp.rename(p)
+    return d
+
+
+def con() -> duckdb.DuckDBPyConnection:
+    global _con
+    if _con is None:
+        d = ensure_files()
+        c = duckdb.connect()
+        c.execute(f"SET memory_limit='{os.environ.get('CFPB_MEMORY_LIMIT', '1GB')}'")
+        c.execute(f"SET threads={int(os.environ.get('CFPB_THREADS', '2'))}")
+        c.execute(f"CREATE VIEW c AS SELECT * FROM read_parquet('{d}/complaints.parquet')")
+        c.execute(f"CREATE VIEW n AS SELECT * FROM read_parquet('{d}/narratives_*.parquet')")
+        _con = c
+    return _con
+
+
+def run(sql: str, params: list[Any] | None = None) -> list[dict]:
+    cur = con().cursor()
+    timer = threading.Timer(QUERY_TIMEOUT_S, cur.interrupt)
+    timer.start()
+    try:
+        cur.execute(sql, params or [])
+        rows = cur.fetchall()
+    except duckdb.InterruptException:
+        raise RuntimeError(f"Query took longer than {QUERY_TIMEOUT_S:.0f}s and was stopped. Add a date range, company or product filter.")
+    finally:
+        timer.cancel()
+    cols = [x[0] for x in cur.description]
+    return [{k: (round(v, 4) if isinstance(v, float) else (v.isoformat() if isinstance(v, date) else v)) for k, v in zip(cols, r)} for r in rows]
+
+
+# ---------------- names and filters ----------------
+STATES = set("AL AK AZ AR CA CO CT DE DC FL GA HI ID IL IN IA KS KY LA ME MD MA MI MN MS MO MT NE NV NH NJ NM NY NC ND OH OK OR PA RI SC SD TN TX UT VT VA WA WV WI WY AS GU MP PR VI UM FM MH PW AA AE AP".split())
+GROUPS = {
+    "year": "year(c.date_received)", "quarter": "strftime(c.date_received, '%Y') || '-Q' || cast(quarter(c.date_received) AS VARCHAR)",
+    "month": "strftime(c.date_received, '%Y-%m')", "product": "c.product", "sub_product": "c.sub_product", "issue": "c.issue",
+    "sub_issue": "c.sub_issue", "company": "c.company", "state": "c.state", "company_response": "c.company_response",
+    "company_public_response": "c.company_public_response", "submitted_via": "c.submitted_via", "timely_response": "c.timely_response",
+}
+STATUS_HINT = "In progress and Untimely response are CFPB response categories, not outcomes."
+
+
+def _d(v: Optional[str], name: str, end: bool = False) -> Optional[str]:
+    """YYYY-MM-DD passes through. YYYY-MM means the first day, or the last day when end=True (date_to)."""
+    if v is None or v == "":
+        return None
+    if not re.fullmatch(r"\d{4}-\d{2}(-\d{2})?", v):
+        raise ValueError(f"{name} must be YYYY-MM-DD or YYYY-MM, got {v!r}")
+    try:
+        if len(v) == 7:
+            y, m = int(v[:4]), int(v[5:])
+            if end:
+                import calendar
+                return f"{v}-{calendar.monthrange(y, m)[1]:02d}"
+            date(y, m, 1)
+            return v + "-01"
+        date.fromisoformat(v)
+    except ValueError:
+        raise ValueError(f"{name} is not a real date: {v!r}")
+    return v
+
+
+def _filters(company=None, company_contains=None, product=None, sub_product=None, issue=None, state=None,
+             date_from=None, date_to=None, company_response=None, timely=None, submitted_via=None, tag=None,
+             has_narrative=None, prefix="c."):
+    w: list[str] = []
+    p: list[Any] = []
+    if company:
+        w.append(f"{prefix}company = ?"); p.append(company)
+    if company_contains:
+        w.append(f"{prefix}company ILIKE ?"); p.append(f"%{company_contains}%")
+    for col, v in (("product", product), ("sub_product", sub_product), ("issue", issue), ("company_response", company_response),
+                   ("submitted_via", submitted_via)):
+        if v:
+            w.append(f"{prefix}{col} ILIKE ?"); p.append(v)
+    if state:
+        s = state.upper().strip()
+        if s not in STATES:
+            raise ValueError(f"state must be a two-letter code, got {state!r}")
+        w.append(f"{prefix}state = ?"); p.append(s)
+    f, t = _d(date_from, "date_from"), _d(date_to, "date_to", end=True)
+    if f:
+        w.append(f"{prefix}date_received >= CAST(? AS DATE)"); p.append(f)
+    if t:
+        w.append(f"{prefix}date_received <= CAST(? AS DATE)"); p.append(t)
+    if timely is not None:
+        w.append(f"{prefix}timely_response = ?"); p.append("Yes" if timely else "No")
+    if tag:
+        w.append(f"{prefix}tags ILIKE ?"); p.append(f"%{tag}%")
+    if has_narrative is True:
+        w.append(f"{prefix}complaint_id IN (SELECT complaint_id FROM n)")
+    elif has_narrative is False:
+        w.append(f"{prefix}complaint_id NOT IN (SELECT complaint_id FROM n)")
+    return (" AND ".join(w) or "TRUE"), p
+
+
+FILTER_DOC = (
+    "Filters: company (exact name as in find_company), company_contains (substring), product, sub_product, issue, "
+    "company_response (exact CFPB value, case-insensitive), submitted_via, state (2 letters), tag (e.g. 'Servicemember', 'Older American'), "
+    "timely (true/false), date_from/date_to (YYYY-MM-DD or YYYY-MM, on date received)."
+)
+
+METRICS = (
+    "count(*) AS complaints, "
+    "round(avg(CASE WHEN c.timely_response='Yes' THEN 1.0 WHEN c.timely_response='No' THEN 0.0 END), 4) AS timely_rate, "
+    "round(avg(CASE WHEN c.company_response='Closed with monetary relief' THEN 1.0 ELSE 0.0 END), 4) AS monetary_relief_rate, "
+    "round(avg(CASE WHEN c.company_response='Closed with non-monetary relief' THEN 1.0 ELSE 0.0 END), 4) AS nonmonetary_relief_rate, "
+    "round(avg(CASE WHEN c.company_response='In progress' THEN 1.0 ELSE 0.0 END), 4) AS in_progress_rate"
+)
+
+
+def _page(limit: int, offset: int) -> tuple[int, int]:
+    return max(1, min(int(limit), MAX_ROWS)), max(0, int(offset))
+
+
+# ---------------- tools ----------------
+@mcp.tool(description="What this dataset is: row counts, date ranges, narrative coverage, and the narrative freeze. Call first when unsure about coverage.")
+def dataset_info() -> dict:
+    r = run("SELECT count(*) AS complaints, min(date_received) AS first_received, max(date_received) AS last_received, "
+            "count(DISTINCT company) AS companies, count(DISTINCT product) AS products FROM c")[0]
+    nn = run("SELECT count(*) AS narratives, min(complaint_id) AS min_id FROM n")[0]
+    r["narratives"] = nn["narratives"]
+    r["narratives_note"] = (f"Narratives come from CFPB's FOIA Reading Room archive, frozen at {NARRATIVE_FREEZE}: CFPB stopped publishing "
+                            "narratives in September 2026. Complaints published after that have none, and none exist before 2015.")
+    r["note"] = NOTE
+    r["latest_complaint_year_partial"] = True
+    return r
+
+
+@mcp.tool(description="List the values of a field with complaint counts, to find exact product/issue/response names. "
+                      "field is one of: product, sub_product, issue, sub_issue, company_response, company_public_response, submitted_via, state, timely_response. "
+                      "Optional search narrows by substring; product narrows issues to that product. " + FILTER_DOC)
+def list_values(field: str, search: Optional[str] = None, product: Optional[str] = None, limit: int = 50) -> list[dict]:
+    allowed = ["product", "sub_product", "issue", "sub_issue", "company_response", "company_public_response", "submitted_via", "state", "timely_response"]
+    if field not in allowed:
+        raise ValueError(f"field must be one of {allowed}. For company names use find_company.")
+    where, p = ["c." + field + " IS NOT NULL"], []
+    if search:
+        where.append(f"c.{field} ILIKE ?"); p.append(f"%{search}%")
+    if product:
+        where.append("c.product ILIKE ?"); p.append(product)
+    limit, _ = _page(limit, 0)
+    return run(f"SELECT c.{field} AS value, count(*) AS complaints FROM c WHERE {' AND '.join(where)} GROUP BY 1 ORDER BY 2 DESC LIMIT {limit}", p)
+
+
+@mcp.tool(description="Find companies by name. CFPB lists the same firm under variants and subsidiaries (e.g. 'EQUIFAX, INC.', 'Equifax Information Services LLC'), "
+                      "so this returns every matching name with complaint counts and first/last dates; pass the exact names you want to other tools via company, "
+                      "or use company_contains for all variants at once.")
+def find_company(name: str, limit: int = 25) -> list[dict]:
+    limit, _ = _page(limit, 0)
+    toks = [t for t in re.split(r"[^A-Za-z0-9]+", name) if t]
+    if not toks:
+        raise ValueError("name is empty")
+    where = " AND ".join("c.company ILIKE ?" for _ in toks)
+    return run(f"SELECT c.company, count(*) AS complaints, min(c.date_received) AS first_received, max(c.date_received) AS last_received "
+               f"FROM c WHERE {where} GROUP BY 1 ORDER BY 2 DESC LIMIT {limit}", [f"%{t}%" for t in toks])
+
+
+@mcp.tool(description="Count complaints, optionally grouped. group_by is one or two of: " + ", ".join(GROUPS) + ". Returns complaints, timely_rate, "
+                      "monetary_relief_rate, nonmonetary_relief_rate, in_progress_rate per group (rates are fractions of that group's complaints). "
+                      "Counts are raw complaint counts, not adjusted for company size. " + STATUS_HINT + " " + FILTER_DOC)
+def complaint_counts(group_by: Optional[list[str]] = None, company: Optional[str] = None, company_contains: Optional[str] = None,
+                     product: Optional[str] = None, sub_product: Optional[str] = None, issue: Optional[str] = None, state: Optional[str] = None,
+                     date_from: Optional[str] = None, date_to: Optional[str] = None, company_response: Optional[str] = None,
+                     timely: Optional[bool] = None, submitted_via: Optional[str] = None, tag: Optional[str] = None,
+                     has_narrative: Optional[bool] = None, order_by: str = "complaints", limit: int = 25, offset: int = 0) -> list[dict]:
+    gb = group_by or []
+    if len(gb) > 2:
+        raise ValueError("group_by takes at most two fields")
+    for g in gb:
+        if g not in GROUPS:
+            raise ValueError(f"unknown group_by {g!r}; choose from {list(GROUPS)}")
+    limit, offset = _page(limit, offset)
+    where, p = _filters(company, company_contains, product, sub_product, issue, state, date_from, date_to, company_response, timely, submitted_via, tag, has_narrative)
+    sel = ", ".join(f"{GROUPS[g]} AS {g}" for g in gb)
+    grp = f" GROUP BY {', '.join(str(i + 1) for i in range(len(gb)))}" if gb else ""
+    ob = order_by if order_by in ("complaints", "timely_rate", "monetary_relief_rate") else "complaints"
+    chrono = gb and gb[0] in ("year", "quarter", "month")
+    order = f" ORDER BY {'1 ASC' if chrono else ob + ' DESC'}" + (f", {ob} DESC" if chrono and len(gb) > 1 else "")
+    rows = run(f"SELECT {sel + ', ' if sel else ''}{METRICS} FROM c WHERE {where}{grp}{order} LIMIT {limit + 1} OFFSET {offset}", p)
+    if len(rows) > limit:
+        rows = rows[:limit]
+        rows.append({"truncated": True, "next_offset": offset + limit, "message": "More groups exist; raise offset or narrow filters."})
+    return rows
+
+
+@mcp.tool(description="Complaints over time (month, quarter or year), for one filter set. Set period to month, quarter or year. "
+                      "The latest period is partial. " + STATUS_HINT + " " + FILTER_DOC)
+def trend(period: str = "month", company: Optional[str] = None, company_contains: Optional[str] = None, product: Optional[str] = None,
+          issue: Optional[str] = None, state: Optional[str] = None, date_from: Optional[str] = None, date_to: Optional[str] = None,
+          company_response: Optional[str] = None, tag: Optional[str] = None, submitted_via: Optional[str] = None) -> list[dict]:
+    if period not in ("month", "quarter", "year"):
+        raise ValueError("period must be month, quarter or year")
+    where, p = _filters(company, company_contains, product, None, issue, state, date_from, date_to, company_response, None, submitted_via, tag)
+    return run(f"SELECT {GROUPS[period]} AS {period}, {METRICS} FROM c WHERE {where} GROUP BY 1 ORDER BY 1 LIMIT 1000", p)
+
+
+@mcp.tool(description="Profile of one company (or all name variants via company_contains): totals, first/last complaint, top products, issues, states, "
+                      "response outcomes, yearly counts. Counts are not adjusted for company size. Optional date_from/date_to/product.")
+def company_profile(company: Optional[str] = None, company_contains: Optional[str] = None, date_from: Optional[str] = None,
+                    date_to: Optional[str] = None, product: Optional[str] = None) -> dict:
+    if not company and not company_contains:
+        raise ValueError("pass company (exact) or company_contains")
+    where, p = _filters(company, company_contains, product, None, None, None, date_from, date_to, None, None, None, None)
+    tot = run(f"SELECT {METRICS}, min(c.date_received) AS first_received, max(c.date_received) AS last_received, count(DISTINCT c.company) AS name_variants FROM c WHERE {where}", p)[0]
+    if not tot["complaints"]:
+        return {"complaints": 0, "message": "No complaints match. Use find_company to see exact names."}
+    def top(col, k=8):
+        return run(f"SELECT c.{col} AS value, count(*) AS complaints FROM c WHERE {where} AND c.{col} IS NOT NULL GROUP BY 1 ORDER BY 2 DESC LIMIT {k}", p)
+    return {**tot, "names_matched": run(f"SELECT c.company, count(*) AS complaints FROM c WHERE {where} GROUP BY 1 ORDER BY 2 DESC LIMIT 10", p),
+            "top_products": top("product"), "top_issues": top("issue"), "top_states": top("state"), "responses": top("company_response", 10),
+            "by_year": run(f"SELECT year(c.date_received) AS year, count(*) AS complaints FROM c WHERE {where} GROUP BY 1 ORDER BY 1", p),
+            "narratives_available": run(f"SELECT count(*) AS n FROM c WHERE {where} AND c.complaint_id IN (SELECT complaint_id FROM n)", p)[0]["n"]}
+
+
+@mcp.tool(description="Side-by-side comparison of up to 6 companies on the same filters: complaints, timely_rate, relief rates, top product and top issue each. "
+                      "Each entry in companies is matched as a substring on the company name (all variants combined). Counts are not adjusted for company size.")
+def compare_companies(companies: list[str], product: Optional[str] = None, issue: Optional[str] = None, state: Optional[str] = None,
+                      date_from: Optional[str] = None, date_to: Optional[str] = None) -> list[dict]:
+    if not companies or len(companies) > 6:
+        raise ValueError("pass 1 to 6 company names")
+    out = []
+    for name in companies:
+        where, p = _filters(None, name, product, None, issue, state, date_from, date_to, None, None, None, None)
+        r = run(f"SELECT {METRICS}, count(DISTINCT c.company) AS name_variants FROM c WHERE {where}", p)[0]
+        r = {"company_search": name, **r}
+        if r["complaints"]:
+            r["top_product"] = run(f"SELECT c.product AS v FROM c WHERE {where} GROUP BY 1 ORDER BY count(*) DESC LIMIT 1", p)[0]["v"]
+            r["top_issue"] = run(f"SELECT c.issue AS v FROM c WHERE {where} GROUP BY 1 ORDER BY count(*) DESC LIMIT 1", p)[0]["v"]
+        out.append(r)
+    return out
+
+
+def _snippet(text: str, terms: list[str], width: int = 450) -> str:
+    low = text.lower()
+    pos = min([i for i in (low.find(t.lower()) for t in terms) if i >= 0] or [0])
+    s = max(0, pos - width // 3)
+    seg = text[s:s + width].strip()
+    return ("..." if s else "") + seg + ("..." if s + width < len(text) else "")
+
+
+@mcp.tool(description="Keyword search over archived complaint narratives (frozen at " + NARRATIVE_FREEZE + "; CFPB stopped publishing them in September 2026). "
+                      "query: words that must all appear (case-insensitive), or use phrase for an exact phrase, or any_of for alternatives. "
+                      "Returns a snippet per complaint plus its structured fields; use get_complaint for the full text. A date, company or product filter makes it much faster. "
+                      + FILTER_DOC)
+def search_narratives(query: Optional[str] = None, phrase: Optional[str] = None, any_of: Optional[list[str]] = None,
+                      company: Optional[str] = None, company_contains: Optional[str] = None, product: Optional[str] = None,
+                      sub_product: Optional[str] = None, issue: Optional[str] = None, state: Optional[str] = None,
+                      date_from: Optional[str] = None, date_to: Optional[str] = None, company_response: Optional[str] = None,
+                      timely: Optional[bool] = None, tag: Optional[str] = None, limit: int = 10, offset: int = 0) -> list[dict]:
+    words = [w for w in re.split(r"\s+", (query or "").strip()) if w]
+    if not (words or phrase or any_of):
+        raise ValueError("pass query, phrase or any_of")
+    limit, offset = _page(limit, offset)
+    limit = min(limit, 25)
+    where, p = _filters(company, company_contains, product, sub_product, issue, state, date_from, date_to, company_response, timely, None, tag)
+    conds, tp = [], []
+    for w in words:
+        conds.append("contains(lower(n.narrative), ?)"); tp.append(w.lower())
+    if phrase:
+        conds.append("contains(lower(n.narrative), ?)"); tp.append(phrase.lower())
+    if any_of:
+        conds.append("(" + " OR ".join("contains(lower(n.narrative), ?)" for _ in any_of) + ")"); tp += [a.lower() for a in any_of]
+    sql = (f"SELECT c.complaint_id, c.date_received, c.company, c.product, c.issue, c.state, c.company_response, n.narrative "
+           f"FROM c JOIN n USING (complaint_id) WHERE {where} AND {' AND '.join(conds)} ORDER BY c.date_received DESC, c.complaint_id DESC "
+           f"LIMIT {limit + 1} OFFSET {offset}")
+    rows = run(sql, p + tp)
+    terms = words + ([phrase] if phrase else []) + (any_of or [])
+    more = len(rows) > limit
+    out = []
+    for r in rows[:limit]:
+        t = r.pop("narrative")
+        r["snippet"] = _snippet(t, terms)
+        out.append(r)
+    if more:
+        out.append({"truncated": True, "next_offset": offset + limit, "message": "More matches exist; raise offset, or narrow filters. Results are newest first."})
+    if not out:
+        out.append({"message": f"No narratives matched. Narratives exist only for complaints published by CFPB with a narrative through {NARRATIVE_FREEZE} (none for complaints received before 2015)."})
+    return out
+
+
+@mcp.tool(description="Count how many archived narratives match a keyword search, optionally grouped by year, product, company, issue or state. "
+                      "Same search arguments as search_narratives. Use this for 'how many complaints mention X'. Counts only complaints that have a narrative (through "
+                      + NARRATIVE_FREEZE + "), not all complaints. " + FILTER_DOC)
+def count_narratives(query: Optional[str] = None, phrase: Optional[str] = None, any_of: Optional[list[str]] = None, group_by: Optional[str] = None,
+                     company: Optional[str] = None, company_contains: Optional[str] = None, product: Optional[str] = None,
+                     issue: Optional[str] = None, state: Optional[str] = None, date_from: Optional[str] = None, date_to: Optional[str] = None,
+                     limit: int = 25) -> list[dict]:
+    if group_by and group_by not in ("year", "product", "company", "issue", "state", "month"):
+        raise ValueError("group_by must be year, month, product, company, issue or state")
+    words = [w for w in re.split(r"\s+", (query or "").strip()) if w]
+    where, p = _filters(company, company_contains, product, None, issue, state, date_from, date_to, None, None, None, None)
+    conds, tp = [], []
+    for w in words:
+        conds.append("contains(lower(n.narrative), ?)"); tp.append(w.lower())
+    if phrase:
+        conds.append("contains(lower(n.narrative), ?)"); tp.append(phrase.lower())
+    if any_of:
+        conds.append("(" + " OR ".join("contains(lower(n.narrative), ?)" for _ in any_of) + ")"); tp += [a.lower() for a in any_of]
+    cond = (" AND " + " AND ".join(conds)) if conds else ""
+    limit, _ = _page(limit, 0)
+    sel = f"{GROUPS[group_by]} AS {group_by}, " if group_by else ""
+    grp = " GROUP BY 1 ORDER BY " + ("1" if group_by in ("year", "month") else "2 DESC") if group_by else ""
+    return run(f"SELECT {sel}count(*) AS narratives FROM c JOIN n USING (complaint_id) WHERE {where}{cond}{grp} LIMIT {limit}", p + tp)
+
+
+@mcp.tool(description="One complaint by its CFPB Complaint ID: all structured fields and, when archived, the full narrative.")
+def get_complaint(complaint_id: int) -> dict:
+    rows = run("SELECT * FROM c WHERE complaint_id = ?", [int(complaint_id)])
+    nr = run("SELECT narrative FROM n WHERE complaint_id = ?", [int(complaint_id)])
+    if not rows and not nr:
+        return {"error": f"Complaint {complaint_id} is not in the dataset. It may be newer than the data, or CFPB may have removed it."}
+    r = rows[0] if rows else {"complaint_id": int(complaint_id), "note": "Narrative is archived but the complaint is no longer in the live CFPB file."}
+    r["narrative"] = nr[0]["narrative"] if nr else None
+    if not nr:
+        r["narrative_note"] = (f"No archived narrative. Narratives exist only for complaints published by CFPB with a narrative through {NARRATIVE_FREEZE} (none for complaints received before 2015) where the consumer consented to publish.")
+    return r
+
+
+# ---------------- hosting ----------------
+class RateLimit:
+    def __init__(self, app, per_minute: int):
+        self.app, self.per_minute, self.hits = app, per_minute, {}
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http" and scope["path"] != "/healthz":
+            h = dict(scope["headers"])
+            ip = (h.get(b"fly-client-ip") or h.get(b"x-forwarded-for", b"").split(b",")[0] or b"?").decode().strip()
+            now = time.time()
+            q_ = [t for t in self.hits.get(ip, []) if now - t < 60]
+            if len(q_) >= self.per_minute:
+                await send({"type": "http.response.start", "status": 429, "headers": [(b"content-type", b"application/json"), (b"retry-after", b"60")]})
+                await send({"type": "http.response.body", "body": b'{"error":"rate limit exceeded, try again in a minute"}'})
+                return
+            q_.append(now)
+            self.hits[ip] = q_
+            if len(self.hits) > 5000:
+                self.hits = {k: v for k, v in self.hits.items() if v and now - v[-1] < 60}
+        await self.app(scope, receive, send)
+
+
+def _forbid_extra_arguments() -> None:
+    for t in mcp._tool_manager.list_tools():
+        model = t.fn_metadata.arg_model
+        model.model_config["extra"] = "forbid"
+        model.model_rebuild(force=True)
+
+
+_forbid_extra_arguments()
+
+
+def http_app():
+    from mcp.server.transport_security import TransportSecuritySettings
+    from starlette.responses import JSONResponse
+    hosts = [h for h in os.environ.get("CFPB_ALLOWED_HOSTS", "").split(",") if h]
+    mcp.settings.stateless_http = True
+    mcp.settings.json_response = True
+    mcp.settings.transport_security = TransportSecuritySettings(
+        enable_dns_rebinding_protection=bool(hosts), allowed_hosts=hosts, allowed_origins=["*"] if hosts else [])
+
+    @mcp.custom_route("/data/{name}", methods=["GET"])
+    async def data_file(request):
+        from starlette.responses import FileResponse
+        name = request.path_params["name"]
+        p = data_dir() / name
+        if name not in FILES or not p.exists():
+            return JSONResponse({"error": "not found"}, status_code=404)
+        return FileResponse(p, media_type="application/octet-stream", filename=name)
+
+    @mcp.custom_route("/healthz", methods=["GET"])
+    async def healthz(request):
+        return JSONResponse({"ok": True})
+
+    return RateLimit(mcp.streamable_http_app(), int(os.environ.get("CFPB_RATE_PER_MIN", "60")))
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if "--check" in argv:
+        ensure_files()
+        print(dataset_info())
+        return
+    if "--http" in argv:
+        import uvicorn
+        uvicorn.run(http_app(), host=os.environ.get("HOST", "0.0.0.0"), port=int(os.environ.get("PORT", "8080")), log_level="warning", timeout_keep_alive=5)
+        return
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: cfpb-complaints-analysis
+Version: 0.1.0
+Summary: CFPB Consumer Complaint Database as clean Parquet plus an MCP server: 18M complaints and 3.85M archived narratives
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb>=1.0
+Requires-Dist: mcp<2,>=1.2
+Dynamic: license-file
+
+# cfpb-complaints-analysis
+
+The CFPB Consumer Complaint Database as clean Parquet, plus an MCP server so an AI assistant can query it: 18.2 million complaints (2011 to today) and 3.85 million consumer narratives.
+
+## What is in it
+
+| Layer | Source | Coverage |
+|---|---|---|
+| Structured complaints | CFPB's public complaint file, `files.consumerfinance.gov/ccdb/complaints.csv.zip` | 18,239,728 complaints, received 2011-12-01 to 2026-10-07 (rebuild to refresh) |
+| Narratives | CFPB FOIA Reading Room, "CFPB Consumer Complaint Database Narratives Archive" | 3,851,415 narratives, published through 2026-08-14, none before 2015 |
+
+Both are CFPB's own files. Nothing comes from a third party. CFPB describes the narratives as public domain for FOIA purposes, and says on its data page that complaint data is "freely available for anyone to use, analyze, and build on."
+
+## The narrative freeze
+
+CFPB stopped publishing complaint narratives in September 2026 (database release 24, and the Aug 14, 2026 announcement that it would cease discretionary publication of narratives and visualizations). It moved the previously published narratives to its FOIA Reading Room. The live complaint file has no narrative column any more.
+
+This project joins the archived narratives back to the live complaints by Complaint ID. So:
+
+- Narratives exist only for complaints CFPB had published with one through 2026-08-14. Complaints from after that have none, and it will stay that way.
+- Fewer than half of complaints ever had a narrative: the consumer had to consent, and none were published before 2015.
+- Narratives are scrubbed by CFPB (personal data shows as XXXX).
+- Structured fields keep updating when you rebuild from CFPB's live file.
+
+## Use it
+
+```
+pip install cfpb-complaints-analysis
+cfpb-complaints-mcp
+```
+
+The first run downloads the Parquet files (about 700 MB) from the hosted service to `~/.cache/cfpb-complaints-analysis`. Set `CFPB_DATA_URL` to fetch them from somewhere else, or `CFPB_DATA_DIR` to use a folder you built yourself. Add the server to your MCP client as a stdio command, or use the hosted endpoint listed in the MCP registry as `io.github.bnovarini/cfpb-complaints-analysis`.
+
+Tools: `dataset_info`, `list_values`, `find_company`, `complaint_counts`, `trend`, `company_profile`, `compare_companies`, `search_narratives`, `count_narratives`, `get_complaint`.
+
+Example questions: What do people complain about at Navy Federal versus PenFed? How did mortgage complaints about Rocket change by year? Find 2024 narratives that mention "overdraft fee" at a credit union.
+
+Build it yourself from CFPB's sources: `cfpb-complaints --data data build`.
+
+## Read this before quoting numbers
+
+- Complaints are unverified consumer allegations. CFPB says so itself.
+- Counts are raw. A large company will have more complaints than a small one; nothing is scaled by customers or accounts.
+- CFPB lists some firms under several names. Use `find_company` and `company_contains` to include all variants.
+- The newest months are partial: complaints are still being sent to companies, and "In progress" is a status, not an outcome.
+- Keyword narrative search scans text. Unfiltered searches take about ten seconds. A date, company or product filter makes them much faster.
+
+## Checks
+
+Every count is reconciled to CFPB's own published numbers. See [docs/AUDIT.md](docs/AUDIT.md), including the figures that do not match and why.
+
+## License
+
+MIT for the code. The data is CFPB's.

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/cfpb_complaints/__init__.py
+src/cfpb_complaints/__main__.py
+src/cfpb_complaints/build.py
+src/cfpb_complaints/cli.py
+src/cfpb_complaints/mcp_server.py
+src/cfpb_complaints_analysis.egg-info/PKG-INFO
+src/cfpb_complaints_analysis.egg-info/SOURCES.txt
+src/cfpb_complaints_analysis.egg-info/dependency_links.txt
+src/cfpb_complaints_analysis.egg-info/entry_points.txt
+src/cfpb_complaints_analysis.egg-info/requires.txt
+src/cfpb_complaints_analysis.egg-info/top_level.txt
+tests/test_server.py

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cfpb-complaints = cfpb_complaints.cli:main
+cfpb-complaints-mcp = cfpb_complaints.mcp_server:main

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/requires.txt

@@ -0,0 +1,2 @@
+duckdb>=1.0
+mcp<2,>=1.2

cfpb_complaints_analysis-0.1.0/src/cfpb_complaints_analysis.egg-info/top_level.txt

@@ -0,0 +1 @@
+cfpb_complaints

cfpb_complaints_analysis-0.1.0/tests/test_server.py

@@ -0,0 +1,29 @@
+import os, pathlib, pytest
+
+d = os.environ.get("CFPB_DATA_DIR")
+pytestmark = pytest.mark.skipif(not d or not (pathlib.Path(d) / "complaints.parquet").exists(), reason="needs CFPB_DATA_DIR with the Parquet files")
+
+
+def test_filters_validate():
+    from cfpb_complaints.mcp_server import _filters
+    with pytest.raises(ValueError):
+        _filters(state="Texas")
+    with pytest.raises(ValueError):
+        _filters(date_from="01/02/2024")
+    w, p = _filters(company_contains="navy", date_from="2024-01")
+    assert "company ILIKE" in w and p[-1] == "2024-01-01"
+
+
+def test_counts_and_search():
+    from cfpb_complaints.mcp_server import complaint_counts, search_narratives, get_complaint
+    r = complaint_counts(group_by=["year"], date_from="2024-01", date_to="2024-12")
+    assert r[0]["year"] == 2024 and r[0]["complaints"] == 2734268
+    s = search_narratives(phrase="overdraft fee", date_from="2024-01", date_to="2024-01", limit=2)
+    assert s and "snippet" in s[0]
+    assert get_complaint(1)["error"]
+
+
+def test_unknown_group_by_rejected():
+    from cfpb_complaints.mcp_server import complaint_counts
+    with pytest.raises(ValueError):
+        complaint_counts(group_by=["nope"])