big update

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -1,21 +1,61 @@
 ---
 title: 🏘️ Mcp Census
-emoji: 🏢
-colorFrom: red
-colorTo: gray
+emoji: 🏘️
+colorFrom: yellow
+colorTo: indigo
 sdk: gradio
 sdk_version: 5.33.0
 app_file: app.py
 pinned: false
-short_description: mcp-census server build for the agents-mcp-hackathon
+short_description: MCP server leveraging U.S. Census Bureau tooling
 tags:
     - mcp-server-track
 ---
 
-# Possible improvements
+# mcp-census
 
-* Rather than build tool sets for every Census dataset (decennial, american community survey, etc.), it may be more comprensive to build tooling around the [machine readable dataset discovery tool](https://www.census.gov/data/developers/updates/new-discovery-tool.html).
-* The Census Bureau publishes myriad documentation. Enabling semantic retrieval via RAG should provide agents with information to better respond to user queries.
+A work-in-progress MCP server leveraging U.S. Census Bureau tooling for LLM interoperability.
+
+## Example usage
+
+Right now, we recommend using `mcp-census` in conjunction with a MCP Client like Claude Desktop or Cursor. If you prefer to run your own client application, check out [Local Agent Quickstart](#local-agent-quickstart).
+
+**What is the population of Hennepin County, MN for those who are 65 and older?**
+
+https://github.com/user-attachments/assets/c979b9aa-8299-4eec-ad32-362d28ced5e4
+
+**What is the racial/ethnic breakdown of Yolo County?**
+
+https://github.com/user-attachments/assets/d7c34ecb-4503-4bde-a7eb-b865a6f076c8
+
+**Lookup data from the US 2020 Decennial Census and provide a CSV containing data about the number of housing units, total population, and median age for all counties in New York State. For the column containing the county identifier, please provide a complete FIPS containing the state and county as a joined value.**
+
+https://github.com/user-attachments/assets/cffd80f0-0830-4534-ab1a-9574608967ad
+
+## Local MCP server quickstart
+
+We suggest using [`uv`](https://docs.astral.sh/uv/) to manage dependencies, but you can install the required packages directly from the [`pyproject.toml` file](pyproject.toml)
 
 
-Check out the configuration reference at [https://huggingface.co/docs/hub/spaces-config-reference](https://huggingface.co/docs/hub/spaces-config-reference)
+```zsh
+uv run python app.py
+```
+
+Assuming you have no other gradio applications running, this will serve your MCP server at http://localhost:7860/gradio_api/mcp/sse
+
+
+## MCP architecture
+
+<img src="assets/mcp-census.png" alt="MCP Census" width="200" height="auto">
+
+## Possible improvements
+
+### Evaluation
+
+* We recommend starting here to provide a strong benchmark with which to evaluate improvements.
+* MCP server tools can be evaluated via unit tests. Agentic behavior can be evaluated on criteria described [here](https://hamel.dev/blog/posts/evals/) and emerging frameworks such as [RAGAS](https://docs.ragas.io/en/stable/).
+
+### MCP Client
+
+* Rather than build tool sets for every Census dataset (decennial, american community survey, etc.), it may be more comprensive to build tooling around the [machine readable dataset discovery tool](https://www.census.gov/data/developers/updates/new-discovery-tool.html).
+* The Census Bureau publishes myriad documentation. Enabling semantic retrieval via RAG should provide agents with information to better respond to user queries.

app.py

@@ -1,14 +1,15 @@
 import gradio as gr
-from mcp_functions.census_api_calls import (
+
+from functions.census_api_calls import (
     dec2020_dp,
     dec2020_dp_fips_lookup,
 )
-from mcp_functions.census_api_docs import (
+from functions.census_api_docs import (
     import_dec2020_datasets_homepage,
     import_dec2020_dp_geographies,
     import_dec2020_dp_variables,
 )
-from mcp_functions.census_utils import (
+from functions.census_utils import (
     dec2020_dhc_semantic_search,
     required_geograpy_hierarchy_parents,
 )
@@ -71,7 +72,7 @@ dec2020_datasets_homepage_interface = gr.Interface(
 )
 
 
-mcp_server_demo = gr.TabbedInterface(
+mcp_server = gr.TabbedInterface(
     [
         dec2020_datasets_homepage_interface,
         dec2020_dp_geographies_interface,
@@ -94,4 +95,4 @@ mcp_server_demo = gr.TabbedInterface(
 
 
 if __name__ == "__main__":
-    mcp_server_demo.launch(mcp_server=True)
+    mcp_server.launch(mcp_server=True)

{mcp_functions → functions}/census_api_calls.py

@@ -6,7 +6,7 @@ from typing import List, Tuple
 import requests
 from dotenv import load_dotenv
 
-from mcp_functions.utils import build_fips_lookup, find_required_parent_geographies
+from functions.utils import build_fips_lookup, find_required_parent_geographies
 
 
 def parse_required_parent_geographies_string(data_str: str) -> List[Tuple[str, str]]:
@@ -110,9 +110,7 @@ def dec2020_dp_fips_lookup(
         )
 
 
-def dec2020_dp(
-    get_variables: str, for_clauses: str, in_clauses: str
-):
+def dec2020_dp(get_variables: str, for_clauses: str, in_clauses: str):
     """
     Fetches demographic profile data from the U.S. Census Bureau API.
 

{mcp_functions → functions}/census_utils.py

@@ -1,9 +1,9 @@
 from typing import List
 
 from langchain_core.documents import Document
-from vector_databases.census_dhc_dp_techdoc import census_dhc_dp_techdoc
 
-from mcp_functions.utils import find_required_parent_geographies
+from functions.utils import find_required_parent_geographies
+from functions.vector_databases.census_dhc_dp_techdoc import census_dhc_dp_techdoc
 
 
 def required_geograpy_hierarchy_parents(geography_hierarchy: str) -> List[str | None]:

{vector_databases → functions/vector_databases}/census_dhc_dp_techdoc/census_dhc_dp_techdoc.py

@@ -5,7 +5,7 @@ from langchain_huggingface import HuggingFaceEmbeddings
 
 def load_pages():
     loader = PyPDFLoader(
-        "vector_databases/census_dhc_dp_techdoc/2020census-demographic-and-housing-characteristics-file-and-demographic-profile-techdoc.pdf"
+        "functions/vector_databases/census_dhc_dp_techdoc/2020census-demographic-and-housing-characteristics-file-and-demographic-profile-techdoc.pdf"
     )
     pages = []
     for page in loader.load():