Remote MCP server deployment by nesanders · Pull Request #2151 · codeforboston/maple

nesanders · 2026-06-01T00:49:47Z

What this does

Adds a remotely deployed MCP (Model Context Protocol) server so AI assistants like Claude and ChatGPT can search MAPLE's database of bills, testimony, and ballot questions in real time via natural language queries.

What's in this PR

MCP server (mcp-server/)

7 search tools: `search_bills`, `search_testimony`, `search_ballot_questions`, `search_policies`, `list_topics`, `list_committees`, `list_sponsors`
HTTP transport (`index-http.ts`) + stdio transport for local use
Hybrid auth: Firebase ID Token or long-lived agent key (`agentKeys` Firestore collection)
Per-token rate limiting: 60 req/min, 1,000 req/day
Dockerfile for Cloud Run deployment

Firebase Function proxy (`functions/src/mcp/proxy.ts`)

`mcpProxy` function exposes the MCP server at `/api/mcp` via Firebase Hosting rewrite
Swaps client's `X-Maple-Token` header for a GCP identity token to call the private Cloud Run service
Clients never see the Cloud Run URL directly

Embedding infrastructure

`createVectorIndexer.ts`: writes embeddings as Firestore `VectorValue` (plain arrays are invisible to vector indexes)
`backfill-embeddings-parallel.ts`: parallel backfill with exponential backoff on quota errors
`migrate-embeddings-to-vector.ts`: one-time migration for existing plain-array embeddings
All required Firestore vector composite indexes added to `firestore.indexes.json`

User guide

New page at `/learn/ai-tools` explaining the feature for non-technical advocates
Added to the Learn nav menu
Linked from the "How MAPLE Uses AI" page

What's deployed to dev

Cloud Run service `maple-mcp-server` (private, max 2 instances, `digital-testimony-dev`)
Firebase Function `mcpProxy` deployed and tested end-to-end ✓
All vector indexes deployed; embeddings backfilled on both dev and prod
Billing budget alert: $60/month (~$2/day) on dev

What's NOT done yet (before prod deploy)

Deploy Cloud Run service + `mcpProxy` function to prod
The `/api/mcp` hosting rewrite activates on next CI hosting deploy — the nav link to `/learn/ai-tools` should not be publicly promoted until that deploy completes
CI/CD pipeline for building and deploying the Cloud Run image on merge

🤖 Generated with Claude Code

- New page at /learn/ai-tools explaining how to connect AI assistants (Claude Desktop, ChatGPT) to MAPLE via MCP - Covers: what MCP is, what users can ask, 4 example prompts, step-by-step setup with validated external links, privacy notes - NavbarLinkAiTools added to Learn dropdown (mobile + desktop) - navigation.aiTools and titles.ai_tools i18n keys added - How MAPLE Uses AI page links to the new guide Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Processes all collections concurrently (CONCURRENCY=8) and retries quota-exhausted requests with exponential backoff (up to 6 retries, 1s base, 2x multiplier + jitter) rather than failing permanently. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…un deploy - mcp-server/Dockerfile: two-stage build (builder compiles TS, runtime installs prod deps only); listens on PORT=8080/HOST=0.0.0.0 for Cloud Run; uses Workload Identity (no credentials file) - mcp-server/.dockerignore: excludes tests, dev scripts, .env files - next.config.js: proxies /api/mcp → MCP_SERVER_URL/mcp when env var is set, keeping the public endpoint at mapletestimony.org/api/mcp Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- rateLimit.ts: 60 req/min + 1,000 req/day per token (in-memory, resets on daily UTC boundary); applied after auth middleware on POST /mcp - index-http.ts: wire in rateLimitMiddleware - Cloud Run service deployed to digital-testimony-dev (us-central1): max-instances=2, 512Mi, 30s timeout, Workload Identity service account - Artifact Registry repo maple-mcp created in us-central1 - Billing budget: $60/month (~$2/day) with 50%/100% alerts Vertex AI QPM quota reduction (200 QPM / ~$1/day) requires manual action in Cloud Console — CLI cannot reduce below service default. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…e Cloud Run - pages/api/mcp.ts: server-side proxy that fetches a Google identity token for Cloud Run IAM and forwards the user's MAPLE token in X-Maple-Authorization; Cloud Run URL never exposed to clients - mcp-server/auth.ts: check X-Maple-Authorization first (proxy path), fall back to Authorization (direct/local path) - next.config.js: remove dead MCP_SERVER_URL rewrite (replaced by API route) - mcp-server/create-agent-key.ts: fix stale /sse curl example → /mcp - IAM: roles/run.invoker granted to Compute Engine and App Engine default service accounts so Next.js Cloud Run can invoke the MCP service - google-auth-library added to main package.json Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- functions/src/mcp/proxy.ts: mcpProxy onRequest function that fetches a Google identity token for Cloud Run IAM and forwards the user MAPLE token in X-Maple-Authorization; Cloud Run stays --no-allow-unauthenticated - functions/src/index.ts: export mcpProxy - firebase.json: add hosting rewrite /api/mcp → mcpProxy (us-central1) - Remove pages/api/mcp.ts — static export doesn't support API routes - google-auth-library added to functions/package.json - AiTools.tsx: add TODO to update connection config once proxy is live - roles/run.invoker granted to App Engine default SA (Firebase Functions) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Picked up automatically by Firebase CLI at deploy time via the .env.digital-testimony-dev file convention. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…Tested as working by connecting Claude to firebase function. - proxy.ts: use GCP metadata server for identity token (google-auth-library getRequestHeaders() returns Headers object, not plain object — bracket access returns undefined); forward Accept + MCP-Protocol-Version headers from client so MCP content negotiation works end-to-end - proxy.ts: remove google-auth-library dependency (metadata server is more reliable in GCP-hosted environments) - auth.ts: add X-Maple-Token header support (Firebase Functions strips Authorization from allUsers-accessible functions); precedence order: X-Maple-Authorization > X-Maple-Token > Authorization - AiTools.tsx: update config snippet to use X-Maple-Token header Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Remove resolved TODO comment - Fix Claude Desktop platform (Mac/Windows, not mobile) - Fix ChatGPT link to consumer-facing help article - Reframe token step in plain language for non-technical users Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel · 2026-06-01T00:49:53Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
maple-dev	Ready	Preview, Comment	Jun 3, 2026 12:16am

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…low diagram Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

J-C-L · 2026-06-09T16:33:48Z

+      <Row>
+        <Col className="py-3">
+          <SectionContainer>
+            <SectionTitle className="p-2">
+              Use AI to research MAPLE data
+            </SectionTitle>
+            <DescrContainer className="py-3 px-4">
+              You can connect AI chat tools like Claude directly to MAPLE's
+              database of bills, testimony, and ballot questions. Ask questions
+              in plain English and get real-time answers drawn from the full
+              legislative record.
+            </DescrContainer>
+            <DescrContainer className="pb-3 px-4">
+              <Internal href="/learn/ai-tools">
+                Learn how to set up AI research tools with your MAPLE account →
+              </Internal>
+            </DescrContainer>
+          </SectionContainer>
+        </Col>
+      </Row>


Might be good to move the text from this section into mapleAI.json for translatability.

J-C-L · 2026-06-09T16:39:36Z

+              You can connect AI chat tools like Claude directly to MAPLE's
+              database of bills, testimony, and ballot questions. Ask questions
+              in plain English and get real-time answers drawn from the full
+              legislative record.


nit: unnecessary period before "Ask". Should be one sentence: "You can connect AI chat tools like Claude directly to MAPLE's database of bills, testimony, and ballot questions, ask question in plain English, and get real-time answers drawn from the full legislative record. "

J-C-L · 2026-06-09T16:48:04Z

This page has a bunch of text that could be moved to a json for next-i18next translatability. Could use mapleAI.json.

J-C-L

This is so great! One small note- we should also update token.tsx here to "url": "https://mapletestimony.org/api/mcp" and here with "X-Maple-Token": "Bearer YOUR_TOKEN_HERE" now that you've done the Firebase Hosting rewrite.

nesanders and others added 12 commits May 29, 2026 17:18

fix: set MCP_SERVER_URL env var for mcpProxy function on dev

30d8d4f

Picked up automatically by Firebase CLI at deploy time via the .env.digital-testimony-dev file convention. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: remove debug logging from mcpProxy function

bbce16f

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: update lockfiles after google-auth-library install

8aa78a7

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: ignore .gcloudignore

4f45cec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

nesanders requested review from Mephistic, alexjball, kiminkim724, mertbagt, mvictor55, sashamaryl and timblais as code owners June 1, 2026 00:49

nesanders changed the title ~~feat: MCP server — AI research tools for MAPLE data~~ Remote MCP server deployment Jun 1, 2026

nesanders self-assigned this Jun 1, 2026

vercel Bot deployed to Preview – maple-dev June 1, 2026 00:56 View deployment

nesanders and others added 3 commits June 2, 2026 17:25

style: apply Prettier formatting

3704e9e

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: gitignore CLAUDE.md (local dev notes)

c5a753a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: merge upstream/main, resolve functions/yarn.lock conflict

5c5a5d3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview – maple-dev June 2, 2026 21:36 View deployment

docs: update implementation plan with current architecture and auth f…

18682b0

…low diagram Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview – maple-dev June 3, 2026 00:07 View deployment

style: apply Prettier formatting to implementation_plan.md

c32d74c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview – maple-dev June 3, 2026 00:16 View deployment

J-C-L reviewed Jun 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Remote MCP server deployment#2151

Remote MCP server deployment#2151
nesanders wants to merge 17 commits into
codeforboston:mainfrom
nesanders:mcp-server-deploy

nesanders commented Jun 1, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

J-C-L Jun 9, 2026

Uh oh!

J-C-L Jun 9, 2026

Uh oh!

J-C-L Jun 9, 2026

Uh oh!

J-C-L left a comment •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

nesanders commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this does

What's in this PR

What's deployed to dev

What's NOT done yet (before prod deploy)

Uh oh!

vercel Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

J-C-L Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

J-C-L Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

J-C-L Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

J-C-L left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nesanders commented Jun 1, 2026 •

edited

Loading

vercel Bot commented Jun 1, 2026 •

edited

Loading

J-C-L left a comment •

edited

Loading