FastMCP Community Awards Assistant

A FastMCP-based internal AI tool for querying and synthesizing structured information from a Maine community awards and resilience-planning spreadsheet.

This project was built to make town-level planning and award data easier to access through a lightweight, assistant-compatible interface. It connects to a Google Sheet, performs exact and fuzzy matching on community names, and returns structured records through an MCP tool layer that can be integrated into higher-level AI workflows.

Overview

The assistant is designed as a bridge between structured civic planning data and LLM-enabled querying. Rather than manually searching spreadsheets, users can retrieve community-specific information programmatically through a simple MCP tool.

At a high level, the system:

• connects to a Google Sheet containing Maine community planning / award records
• normalizes town names for more robust search behavior
• supports exact and fuzzy retrieval
• returns structured row-level results for downstream assistant use
• exposes the logic through a FastMCP server

Why this project matters

This tool reflects an AI-forward internal knowledge workflow: using MCP to make domain-specific structured data accessible to assistant systems in a cleaner and more scalable way.

While the current version focuses on spreadsheet-backed retrieval, the broader idea is to support AI-assisted querying over resilience, planning, and community-awards information without requiring users to navigate raw tabular data directly.

Core functionality

• Google Sheets integration via service account authentication
• exact and fuzzy town-name matching
• ambiguity handling when multiple communities match a query
• MCP tool exposure for assistant-driven workflows
• lightweight debug route for inspecting sheet loading behavior

Example use case

Given a community name such as Cape Elizabeth, the tool can return structured information from the spreadsheet related to that town, including planning or participation data stored in the underlying sheet.

This makes it useful as an internal assistant layer for resilience planning, grant tracking, or town-level information lookup.

Tech stack

• Python
• FastMCP
• gspread
• google-auth / service account credentials
• Starlette
• Google Sheets as the structured data backend

Project structure

.
├── server.py
├── .gitignore
├── README.md
└── credentials.json   # local only, excluded from version control

How it works

1. Load spreadsheet data

The server authenticates with Google Sheets using a service account and reads rows from the configured worksheet.

2. Normalize community names

Town names are normalized to improve fuzzy matching. This includes:

• lowercasing
• trimming whitespace
• removing trailing township
• removing internal spacing differences

3. Search for matches

The tool first checks for exact matches, then falls back to normalized fuzzy matches.

4. Return structured output

The result is returned as structured JSON-like data through the MCP tool interface, making it easy to use within assistant systems or other orchestration layers.

Setup

1. Clone the repository

git clone https://github.com/justing0909/<repo-name>.git
cd <repo-name>

2. Install dependencies

bash pip install fastmcp gspread google-auth starlette

3. Add credentials locally

Place your Google service account credentials file in the project root as: credentials.json

This file is required locally but should never be committed to GitHub.

4. Confirm spreadsheet configuration

In server.py, verify that the following values match your intended setup:

• SPREADSHEET_ID
• SHEET_NAME
• SERVICE_ACCOUNT_FILE

Running locally

Start the MCP server with:

bash python server.py

The server runs with:

• transport: sse
• port: 8000

Available MCP tool

search_town_links(town_name: str) Searches the Maine community awards / planning spreadsheet for a given town name and returns the matching row data.

Behavior

• returns an exact match when found
• returns a fuzzy match when formatting differences exist
• returns an ambiguity message if multiple possible matches are found
• returns a no-match message otherwise

Debug route

A lightweight debug route is available at: /debug

This returns:

• a sample of loaded community names
• the total number of rows loaded from the sheet

Security note

Do not commit any of the following:

• credentials.json
• .env files
• API keys
• service account secrets

The repository is designed so credentials remain local-only.

Current scope

This version is a lightweight internal MCP server focused on structured spreadsheet retrieval. It is best understood as an AI-enablement layer over civic planning and awards data rather than a full conversational system on its own.

• Potential future directions
• metadata-aware filtering beyond town name lookup
• support for multiple worksheets or datasets
• richer assistant integration
• retrieval over additional resilience planning documents
• integration into broader multi-agent or orchestration workflows
• improved logging, validation, and error handling

Author note

This project was built as part of internal AI tooling work, with the goal of making structured resilience-planning data easier to query and use in assistant-driven workflows.