Fed Speech MCP

An MCP (Model Context Protocol) server that retrieves, parses, and analyzes speeches and testimonies from major Federal Reserve officers.

Features

📡 RSS Feed Discovery - Automatically discovers new speeches from Fed RSS feeds
🔍 Index Page Scanning - Backfill capability by scanning yearly index pages
📝 Smart Parsing - Extracts metadata, speaker info, and clean text from Fed HTML pages
📊 Feature Extraction - Detects topics (inflation, rates, labor market, etc.)
⚖️ Importance Scoring - Rule-based scoring for market relevance
💾 JSON Storage - Persistent storage with deduplication
🔌 MCP Interface - Full MCP compatibility for AI assistants

Covered Content

Speakers

Chair of the Federal Reserve
Vice Chair of the Federal Reserve
Federal Reserve Governors

Content Types

Speeches
Congressional Testimony
Prepared Remarks

Installation

Prerequisites

Python 3.10 or higher
uv package manager

Install uv (if you don't have it):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install the Project

cd fed-speech-mcp

# Create virtual environment and install
uv sync

That's it! The virtual environment is created and all dependencies are installed.

🚀 Quick Start: Test Locally in 5 Minutes

Want to see the MCP tools in action before connecting to an AI? Follow these steps:

Step 1: Install

cd fed-speech-mcp
uv sync

Step 2: Fetch Speeches from Fed Website

uv run python scripts/test_local.py refresh --limit 5

You'll see output like:

🔄 REFRESHING SPEECHES FROM FED WEBSITE
==================================================
📡 Discovering documents via RSS feeds...
   Found 20 document(s)

[1/5] Processing: Governor Bowman's Speech on Banking...
   ✅ Fetched 45231 bytes
   ✅ Parsed: Michelle W. Bowman - speech
   ✅ Normalized: fed-speech-a1b2c3d4e5f6
   ✅ Saved (NEW)
...
✅ REFRESH COMPLETE
   Discovered: 5
   New: 5
   Total in storage: 5

Step 3: Explore the Data

View latest speeches:

uv run python scripts/test_local.py latest --limit 3

Output:

📰 LATEST SPEECHES
==================================================
Found 3 speech(es):

1. Speech on Monetary Policy and the Economic Outlook
   📅 2024-12-15
   👤 Jerome H. Powell (Chair)
   📄 speech | 2500 words
   ⭐ high (0.85)
   🏷️  Topics: inflation, rates, labor
   🔗 https://federalreserve.gov/...
   🆔 fed-speech-abc123

Search by keyword:

uv run python scripts/test_local.py search --query "inflation"

Filter by speaker:

uv run python scripts/test_local.py speaker --name "Powell"
uv run python scripts/test_local.py speaker --role "Chair"

Get full speech content:

uv run python scripts/test_local.py get --doc-id fed-speech-abc123

View statistics:

uv run python scripts/test_local.py stats

Step 4: Run All Tests

uv run python scripts/test_local.py all

This runs a complete test suite: refresh → stats → latest → search → filter → get.

Available Test Commands

Command	Description	Example
`refresh`	Fetch new speeches	`--limit 5`, `--include-index`
`latest`	Show latest speeches	`--limit 10`, `--since 2024-01-01`
`search`	Search by keyword	`--query "inflation"`
`speaker`	Filter by speaker	`--name "Powell"`, `--role "Chair"`
`type`	Filter by doc type	`--doc-type testimony`
`get`	Get full speech	`--doc-id fed-speech-xxx`
`stats`	Show statistics	(no options)
`all`	Run all tests	(no options)

Using with AI Assistants

Platform Compatibility Overview

Platform	MCP Support	Setup Method
Claude Desktop	✅ Native	Direct MCP integration
Cursor IDE	✅ Native	Direct MCP integration
ChatGPT	⚠️ Via API	HTTP API wrapper + Custom GPT
Google Gemini	⚠️ Via API	HTTP API wrapper + Google AI Studio
Other AI Tools	⚠️ Via API	HTTP API wrapper

Step-by-Step: Claude Desktop

Claude Desktop has native MCP support. This is the easiest setup.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Locate Claude Desktop Config

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3: Add MCP Server Configuration

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "fed-speech": {
      "command": "uv",
      "args": ["run", "fed-speech-mcp"],
      "cwd": "/path/to/fed-speech-mcp"
    }
  }
}

Note: Replace /path/to/fed-speech-mcp with your actual installation path.

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop. You should see the Fed Speech tools available.

Step 5: Start Using

Ask Claude things like:

"Refresh the Fed speeches and show me the latest ones"
"What did Chair Powell say about inflation recently?"
"Show me all testimony from 2024"

Step-by-Step: Cursor IDE

Cursor IDE also supports MCP natively.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Open Cursor Settings

Open Cursor IDE
Go to Settings (⌘+, on macOS, Ctrl+, on Windows)
Search for "MCP" or navigate to Features → MCP Servers

Step 3: Add MCP Server

Click "Add MCP Server" and configure:

{
  "name": "fed-speech",
  "command": "uv",
  "args": ["run", "fed-speech-mcp"],
  "cwd": "/path/to/fed-speech-mcp"
}

Step 4: Enable and Use

Toggle the server on. You can now use Fed Speech tools in Cursor's AI chat.

Step-by-Step: ChatGPT (Custom GPT)

ChatGPT doesn't support MCP natively, but you can use the HTTP API wrapper.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Start the HTTP API Server

uv run fed-speech-http

The server runs at http://localhost:8000 by default.

Step 3: Expose to Internet (Required for ChatGPT)

Use a tunneling service like ngrok:

# Install ngrok: https://ngrok.com/download
ngrok http 8000

Copy the public URL (e.g., https://abc123.ngrok.io).

Step 4: Create a Custom GPT

Go to ChatGPT
Click your profile → My GPTs → Create a GPT

In the Configure tab:

Name: "Fed Speech Analyst"
Description: "Analyzes Federal Reserve speeches and testimonies"

Instructions:

You are a Federal Reserve speech analyst. Use the available actions to:
1. Fetch latest speeches with get_latest_speeches
2. Search speeches by speaker, type, or keywords
3. Analyze speech content for market-relevant insights
Always refresh speeches first if the user asks about recent content.

Click Create new action and import the OpenAPI schema:

openapi: 3.0.0
info:
  title: Fed Speech API
  version: 1.0.0
servers:
  - url: https://your-ngrok-url.ngrok.io
paths:
  /speeches/latest:
    get:
      operationId: getLatestSpeeches
      summary: Get latest Fed speeches
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: since_date
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of speeches
  /speeches/search:
    get:
      operationId: searchSpeeches
      summary: Search speeches by keyword
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Search results
  /speeches/{doc_id}:
    get:
      operationId: getSpeech
      summary: Get a specific speech
      parameters:
        - name: doc_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Speech details
  /speeches/refresh:
    post:
      operationId: refreshSpeeches
      summary: Fetch new speeches from Fed website
      responses:
        '200':
          description: Refresh result

Step 5: Save and Use

Save your Custom GPT. Now you can ask it questions about Fed speeches!

Step-by-Step: Google Gemini

Google Gemini can use the HTTP API via Google AI Studio or API.

Step 1: Start the HTTP API Server

cd fed-speech-mcp
uv sync
uv run fed-speech-http

Step 2: Expose to Internet

ngrok http 8000

Step 3: Use with Google AI Studio

Go to Google AI Studio
Create a new prompt or chat
In your system instructions, include:

You have access to a Fed Speech API at https://your-ngrok-url.ngrok.io

Available endpoints:
- GET /speeches/latest?limit=10 - Get latest speeches
- GET /speeches/search?query=inflation - Search speeches
- GET /speeches/{doc_id} - Get specific speech
- POST /speeches/refresh - Fetch new speeches
- GET /speeches/by-speaker?name=Powell - Filter by speaker
- GET /speeches/by-type?doc_type=testimony - Filter by type

When users ask about Fed speeches, use these endpoints to fetch data.
Format responses clearly with speaker names, dates, and key points.

Step 4: Use Function Calling (Advanced)

For programmatic use with Gemini API:

import google.generativeai as genai
import requests

# Configure Gemini
genai.configure(api_key="YOUR_API_KEY")

# Define tools for Gemini
tools = [
    {
        "function_declarations": [
            {
                "name": "get_latest_speeches",
                "description": "Get the latest Federal Reserve speeches",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "limit": {"type": "integer", "description": "Max speeches to return"}
                    }
                }
            },
            {
                "name": "search_speeches",
                "description": "Search Fed speeches by keyword",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string", "description": "Search query"}
                    },
                    "required": ["query"]
                }
            }
        ]
    }
]

model = genai.GenerativeModel('gemini-pro', tools=tools)

# Handle function calls
def handle_function_call(fn_name, args):
    base_url = "http://localhost:8000"
    if fn_name == "get_latest_speeches":
        resp = requests.get(f"{base_url}/speeches/latest", params=args)
    elif fn_name == "search_speeches":
        resp = requests.get(f"{base_url}/speeches/search", params=args)
    return resp.json()

# Chat with function calling
chat = model.start_chat()
response = chat.send_message("What are the latest Fed speeches about inflation?")

# Process function calls in response
for part in response.parts:
    if hasattr(part, 'function_call'):
        fn = part.function_call
        result = handle_function_call(fn.name, dict(fn.args))
        # Send result back to model
        response = chat.send_message(str(result))

HTTP API Reference

When using the HTTP API wrapper, these endpoints are available:

Endpoint	Method	Description
`/speeches/latest`	GET	Get latest speeches
`/speeches/search`	GET	Search by keyword
`/speeches/{doc_id}`	GET	Get specific speech
`/speeches/by-speaker`	GET	Filter by speaker
`/speeches/by-type`	GET	Filter by doc type
`/speeches/refresh`	POST	Fetch new speeches
`/speeches/stats`	GET	Get statistics

Query Parameters

limit - Max results (default: 10, max: 50)
since_date - ISO 8601 date filter
start_date / end_date - Date range
name - Speaker name (partial match)
role - "Chair", "Vice Chair", or "Governor"
doc_type - "speech", "testimony", or "prepared_remarks"
query - Search keywords

Running the MCP Server Directly

For native MCP clients:

# Run the MCP server
uv run fed-speech-mcp

# Run the HTTP API server
uv run fed-speech-http

Available Tools

`get_latest_speeches`

Get the latest Federal Reserve speeches, sorted by publication date.

Parameters:

limit (optional): Maximum number of speeches (default: 10, max: 50)
since_date (optional): Only return speeches after this date (ISO 8601)

`get_speeches_by_speaker`

Filter speeches by speaker name and/or role.

Parameters:

name (optional): Speaker name (partial match, e.g., "Powell")
role (optional): "Chair", "Vice Chair", or "Governor"
start_date (optional): Start date filter
end_date (optional): End date filter

`get_speeches_by_type`

Get speeches by document type.

Parameters:

doc_type (required): "speech", "testimony", or "prepared_remarks"
start_date (optional): Start date filter
end_date (optional): End date filter

`get_speech`

Get full content and metadata for a specific speech.

Parameters:

doc_id (required): The unique document identifier

`refresh_speeches`

Fetch new speeches from the Federal Reserve website.

Parameters:

include_index (optional): Also scan index pages (slower but thorough)
years (optional): Years to scan for index pages

`search_speeches`

Search speeches by keyword.

Parameters:

query (required): Search query
limit (optional): Maximum results (default: 10)

`get_speech_stats`

Get statistics about stored speeches.

Output Format

Each speech document contains:

{
  "doc_id": "fed-speech-abc123def456",
  "source": {
    "publisher": "Board of Governors of the Federal Reserve System",
    "collection": "speeches",
    "url": "https://www.federalreserve.gov/...",
    "retrieved_at": "2024-01-15T10:30:00Z"
  },
  "published_at": "2024-01-15T00:00:00Z",
  "title": "Speech Title",
  "speaker": {
    "name": "Jerome H. Powell",
    "role": "Chair",
    "organization": "Board of Governors of the Federal Reserve System"
  },
  "doc_type": "speech",
  "event": {
    "name": "Economic Club of New York",
    "location": "New York, NY"
  },
  "text": {
    "raw": "...",
    "clean": "..."
  },
  "features": {
    "word_count": 2500,
    "language": "en",
    "has_qa": false,
    "topics": {
      "inflation": true,
      "labor_market": true,
      "rates": true,
      "balance_sheet": false,
      "growth": true,
      "financial_stability": false
    }
  },
  "importance": {
    "tier": "high",
    "score": 0.85,
    "reasons": [
      "Speaker is Chair (Jerome H. Powell)",
      "Discusses rates in context of inflation"
    ]
  }
}

Importance Scoring

The importance score is calculated using these rules:

Factor	Adjustment
Chair or Vice Chair speaker	Base: High
Governor speaker	Base: Medium
Testimony	+1 tier
Contains Q&A	+1 tier
Discusses rates + (inflation or labor market)	+1 tier
Word count < 300	-1 tier

Topic Detection

Topics are detected by keyword matching:

Inflation: inflation, prices, CPI, PCE, price stability
Labor Market: employment, unemployment, wages, jobs
Rates: interest rate, fed funds, hike, cut, monetary policy
Balance Sheet: QE, QT, runoff, asset purchases
Growth: GDP, demand, recession, economic activity
Financial Stability: banking, liquidity, stress, systemic risk

Environment Variables

Variable	Description	Default
`FED_SPEECH_DATA_DIR`	Data storage directory	`./data`
`FED_SPEECH_HTTP_TIMEOUT`	HTTP request timeout (seconds)	`30`
`FED_SPEECH_MAX_RETRIES`	Max retry attempts	`3`
`FED_SPEECH_HTTP_PORT`	HTTP API server port	`8000`

Data Storage

data/
├── speeches/           # Processed JSON documents
│   ├── fed-speech-xxx.json
│   └── ...
└── raw/               # Raw HTML content (for traceability)
    ├── 20240115_abc123.html
    └── ...

Development

Running Unit Tests

# Install with dev dependencies
uv sync --dev

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_models.py

# Run with coverage
uv run pytest --cov=fed_speech_mcp

Running Local Integration Tests

# Test all MCP functionality end-to-end
uv run python scripts/test_local.py all

# Test specific functionality
uv run python scripts/test_local.py refresh --limit 3
uv run python scripts/test_local.py search --query "rates"

Project Structure

fed-speech-mcp/
├── src/fed_speech_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server entry point
│   ├── http_server.py     # HTTP API wrapper
│   ├── config.py          # Configuration
│   ├── models/            # Pydantic data models
│   ├── ingestion/         # RSS/index discovery & fetching
│   ├── parsing/           # HTML parsing & normalization
│   ├── features/          # Feature extraction & scoring
│   └── storage/           # JSON storage layer
├── data/                  # Data directory
├── pyproject.toml
└── README.md

License

MIT

Acknowledgments

Data sourced from the Federal Reserve Board.

Fed Speech MCP

An MCP (Model Context Protocol) server that retrieves, parses, and analyzes speeches and testimonies from major Federal Reserve officers.

Features

📡 RSS Feed Discovery - Automatically discovers new speeches from Fed RSS feeds
🔍 Index Page Scanning - Backfill capability by scanning yearly index pages
📝 Smart Parsing - Extracts metadata, speaker info, and clean text from Fed HTML pages
📊 Feature Extraction - Detects topics (inflation, rates, labor market, etc.)
⚖️ Importance Scoring - Rule-based scoring for market relevance
💾 JSON Storage - Persistent storage with deduplication
🔌 MCP Interface - Full MCP compatibility for AI assistants

Covered Content

Speakers

Chair of the Federal Reserve
Vice Chair of the Federal Reserve
Federal Reserve Governors

Content Types

Speeches
Congressional Testimony
Prepared Remarks

Installation

Prerequisites

Python 3.10 or higher
uv package manager

Install uv (if you don't have it):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install the Project

cd fed-speech-mcp

# Create virtual environment and install
uv sync

That's it! The virtual environment is created and all dependencies are installed.

🚀 Quick Start: Test Locally in 5 Minutes

Want to see the MCP tools in action before connecting to an AI? Follow these steps:

Step 1: Install

cd fed-speech-mcp
uv sync

Step 2: Fetch Speeches from Fed Website

uv run python scripts/test_local.py refresh --limit 5

You'll see output like:

🔄 REFRESHING SPEECHES FROM FED WEBSITE
==================================================
📡 Discovering documents via RSS feeds...
   Found 20 document(s)

[1/5] Processing: Governor Bowman's Speech on Banking...
   ✅ Fetched 45231 bytes
   ✅ Parsed: Michelle W. Bowman - speech
   ✅ Normalized: fed-speech-a1b2c3d4e5f6
   ✅ Saved (NEW)
...
✅ REFRESH COMPLETE
   Discovered: 5
   New: 5
   Total in storage: 5

Step 3: Explore the Data

View latest speeches:

uv run python scripts/test_local.py latest --limit 3

Output:

📰 LATEST SPEECHES
==================================================
Found 3 speech(es):

1. Speech on Monetary Policy and the Economic Outlook
   📅 2024-12-15
   👤 Jerome H. Powell (Chair)
   📄 speech | 2500 words
   ⭐ high (0.85)
   🏷️  Topics: inflation, rates, labor
   🔗 https://federalreserve.gov/...
   🆔 fed-speech-abc123

Search by keyword:

uv run python scripts/test_local.py search --query "inflation"

Filter by speaker:

uv run python scripts/test_local.py speaker --name "Powell"
uv run python scripts/test_local.py speaker --role "Chair"

Get full speech content:

uv run python scripts/test_local.py get --doc-id fed-speech-abc123

View statistics:

uv run python scripts/test_local.py stats

Step 4: Run All Tests

uv run python scripts/test_local.py all

This runs a complete test suite: refresh → stats → latest → search → filter → get.

Available Test Commands

Command	Description	Example
`refresh`	Fetch new speeches	`--limit 5`, `--include-index`
`latest`	Show latest speeches	`--limit 10`, `--since 2024-01-01`
`search`	Search by keyword	`--query "inflation"`
`speaker`	Filter by speaker	`--name "Powell"`, `--role "Chair"`
`type`	Filter by doc type	`--doc-type testimony`
`get`	Get full speech	`--doc-id fed-speech-xxx`
`stats`	Show statistics	(no options)
`all`	Run all tests	(no options)

Using with AI Assistants

Platform Compatibility Overview

Platform	MCP Support	Setup Method
Claude Desktop	✅ Native	Direct MCP integration
Cursor IDE	✅ Native	Direct MCP integration
ChatGPT	⚠️ Via API	HTTP API wrapper + Custom GPT
Google Gemini	⚠️ Via API	HTTP API wrapper + Google AI Studio
Other AI Tools	⚠️ Via API	HTTP API wrapper

Step-by-Step: Claude Desktop

Claude Desktop has native MCP support. This is the easiest setup.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Locate Claude Desktop Config

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3: Add MCP Server Configuration

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "fed-speech": {
      "command": "uv",
      "args": ["run", "fed-speech-mcp"],
      "cwd": "/path/to/fed-speech-mcp"
    }
  }
}

Note: Replace /path/to/fed-speech-mcp with your actual installation path.

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop. You should see the Fed Speech tools available.

Step 5: Start Using

Ask Claude things like:

"Refresh the Fed speeches and show me the latest ones"
"What did Chair Powell say about inflation recently?"
"Show me all testimony from 2024"

Step-by-Step: Cursor IDE

Cursor IDE also supports MCP natively.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Open Cursor Settings

Open Cursor IDE
Go to Settings (⌘+, on macOS, Ctrl+, on Windows)
Search for "MCP" or navigate to Features → MCP Servers

Step 3: Add MCP Server

Click "Add MCP Server" and configure:

{
  "name": "fed-speech",
  "command": "uv",
  "args": ["run", "fed-speech-mcp"],
  "cwd": "/path/to/fed-speech-mcp"
}

Step 4: Enable and Use

Toggle the server on. You can now use Fed Speech tools in Cursor's AI chat.

Step-by-Step: ChatGPT (Custom GPT)

ChatGPT doesn't support MCP natively, but you can use the HTTP API wrapper.

Step 1: Install the Package

cd fed-speech-mcp
uv sync

Step 2: Start the HTTP API Server

uv run fed-speech-http

The server runs at http://localhost:8000 by default.

Step 3: Expose to Internet (Required for ChatGPT)

Use a tunneling service like ngrok:

# Install ngrok: https://ngrok.com/download
ngrok http 8000

Copy the public URL (e.g., https://abc123.ngrok.io).

Step 4: Create a Custom GPT

Go to ChatGPT
Click your profile → My GPTs → Create a GPT

In the Configure tab:

Name: "Fed Speech Analyst"
Description: "Analyzes Federal Reserve speeches and testimonies"

Instructions:

You are a Federal Reserve speech analyst. Use the available actions to:
1. Fetch latest speeches with get_latest_speeches
2. Search speeches by speaker, type, or keywords
3. Analyze speech content for market-relevant insights
Always refresh speeches first if the user asks about recent content.

Click Create new action and import the OpenAPI schema:

openapi: 3.0.0
info:
  title: Fed Speech API
  version: 1.0.0
servers:
  - url: https://your-ngrok-url.ngrok.io
paths:
  /speeches/latest:
    get:
      operationId: getLatestSpeeches
      summary: Get latest Fed speeches
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
        - name: since_date
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of speeches
  /speeches/search:
    get:
      operationId: searchSpeeches
      summary: Search speeches by keyword
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Search results
  /speeches/{doc_id}:
    get:
      operationId: getSpeech
      summary: Get a specific speech
      parameters:
        - name: doc_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Speech details
  /speeches/refresh:
    post:
      operationId: refreshSpeeches
      summary: Fetch new speeches from Fed website
      responses:
        '200':
          description: Refresh result

Step 5: Save and Use

Save your Custom GPT. Now you can ask it questions about Fed speeches!

Step-by-Step: Google Gemini

Google Gemini can use the HTTP API via Google AI Studio or API.

Step 1: Start the HTTP API Server

cd fed-speech-mcp
uv sync
uv run fed-speech-http

Step 2: Expose to Internet

ngrok http 8000

Step 3: Use with Google AI Studio

Go to Google AI Studio
Create a new prompt or chat
In your system instructions, include:

You have access to a Fed Speech API at https://your-ngrok-url.ngrok.io

Available endpoints:
- GET /speeches/latest?limit=10 - Get latest speeches
- GET /speeches/search?query=inflation - Search speeches
- GET /speeches/{doc_id} - Get specific speech
- POST /speeches/refresh - Fetch new speeches
- GET /speeches/by-speaker?name=Powell - Filter by speaker
- GET /speeches/by-type?doc_type=testimony - Filter by type

When users ask about Fed speeches, use these endpoints to fetch data.
Format responses clearly with speaker names, dates, and key points.

Step 4: Use Function Calling (Advanced)

For programmatic use with Gemini API:

import google.generativeai as genai
import requests

# Configure Gemini
genai.configure(api_key="YOUR_API_KEY")

# Define tools for Gemini
tools = [
    {
        "function_declarations": [
            {
                "name": "get_latest_speeches",
                "description": "Get the latest Federal Reserve speeches",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "limit": {"type": "integer", "description": "Max speeches to return"}
                    }
                }
            },
            {
                "name": "search_speeches",
                "description": "Search Fed speeches by keyword",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string", "description": "Search query"}
                    },
                    "required": ["query"]
                }
            }
        ]
    }
]

model = genai.GenerativeModel('gemini-pro', tools=tools)

# Handle function calls
def handle_function_call(fn_name, args):
    base_url = "http://localhost:8000"
    if fn_name == "get_latest_speeches":
        resp = requests.get(f"{base_url}/speeches/latest", params=args)
    elif fn_name == "search_speeches":
        resp = requests.get(f"{base_url}/speeches/search", params=args)
    return resp.json()

# Chat with function calling
chat = model.start_chat()
response = chat.send_message("What are the latest Fed speeches about inflation?")

# Process function calls in response
for part in response.parts:
    if hasattr(part, 'function_call'):
        fn = part.function_call
        result = handle_function_call(fn.name, dict(fn.args))
        # Send result back to model
        response = chat.send_message(str(result))

HTTP API Reference

When using the HTTP API wrapper, these endpoints are available:

Endpoint	Method	Description
`/speeches/latest`	GET	Get latest speeches
`/speeches/search`	GET	Search by keyword
`/speeches/{doc_id}`	GET	Get specific speech
`/speeches/by-speaker`	GET	Filter by speaker
`/speeches/by-type`	GET	Filter by doc type
`/speeches/refresh`	POST	Fetch new speeches
`/speeches/stats`	GET	Get statistics

Query Parameters

limit - Max results (default: 10, max: 50)
since_date - ISO 8601 date filter
start_date / end_date - Date range
name - Speaker name (partial match)
role - "Chair", "Vice Chair", or "Governor"
doc_type - "speech", "testimony", or "prepared_remarks"
query - Search keywords

Running the MCP Server Directly

For native MCP clients:

# Run the MCP server
uv run fed-speech-mcp

# Run the HTTP API server
uv run fed-speech-http

Available Tools

`get_latest_speeches`

Get the latest Federal Reserve speeches, sorted by publication date.

Parameters:

limit (optional): Maximum number of speeches (default: 10, max: 50)
since_date (optional): Only return speeches after this date (ISO 8601)

`get_speeches_by_speaker`

Filter speeches by speaker name and/or role.

Parameters:

name (optional): Speaker name (partial match, e.g., "Powell")
role (optional): "Chair", "Vice Chair", or "Governor"
start_date (optional): Start date filter
end_date (optional): End date filter

`get_speeches_by_type`

Get speeches by document type.

Parameters:

doc_type (required): "speech", "testimony", or "prepared_remarks"
start_date (optional): Start date filter
end_date (optional): End date filter

`get_speech`

Get full content and metadata for a specific speech.

Parameters:

doc_id (required): The unique document identifier

`refresh_speeches`

Fetch new speeches from the Federal Reserve website.

Parameters:

include_index (optional): Also scan index pages (slower but thorough)
years (optional): Years to scan for index pages

`search_speeches`

Search speeches by keyword.

Parameters:

query (required): Search query
limit (optional): Maximum results (default: 10)

`get_speech_stats`

Get statistics about stored speeches.

Output Format

Each speech document contains:

{
  "doc_id": "fed-speech-abc123def456",
  "source": {
    "publisher": "Board of Governors of the Federal Reserve System",
    "collection": "speeches",
    "url": "https://www.federalreserve.gov/...",
    "retrieved_at": "2024-01-15T10:30:00Z"
  },
  "published_at": "2024-01-15T00:00:00Z",
  "title": "Speech Title",
  "speaker": {
    "name": "Jerome H. Powell",
    "role": "Chair",
    "organization": "Board of Governors of the Federal Reserve System"
  },
  "doc_type": "speech",
  "event": {
    "name": "Economic Club of New York",
    "location": "New York, NY"
  },
  "text": {
    "raw": "...",
    "clean": "..."
  },
  "features": {
    "word_count": 2500,
    "language": "en",
    "has_qa": false,
    "topics": {
      "inflation": true,
      "labor_market": true,
      "rates": true,
      "balance_sheet": false,
      "growth": true,
      "financial_stability": false
    }
  },
  "importance": {
    "tier": "high",
    "score": 0.85,
    "reasons": [
      "Speaker is Chair (Jerome H. Powell)",
      "Discusses rates in context of inflation"
    ]
  }
}

Importance Scoring

The importance score is calculated using these rules:

Factor	Adjustment
Chair or Vice Chair speaker	Base: High
Governor speaker	Base: Medium
Testimony	+1 tier
Contains Q&A	+1 tier
Discusses rates + (inflation or labor market)	+1 tier
Word count < 300	-1 tier

Topic Detection

Topics are detected by keyword matching:

Inflation: inflation, prices, CPI, PCE, price stability
Labor Market: employment, unemployment, wages, jobs
Rates: interest rate, fed funds, hike, cut, monetary policy
Balance Sheet: QE, QT, runoff, asset purchases
Growth: GDP, demand, recession, economic activity
Financial Stability: banking, liquidity, stress, systemic risk

Environment Variables

Variable	Description	Default
`FED_SPEECH_DATA_DIR`	Data storage directory	`./data`
`FED_SPEECH_HTTP_TIMEOUT`	HTTP request timeout (seconds)	`30`
`FED_SPEECH_MAX_RETRIES`	Max retry attempts	`3`
`FED_SPEECH_HTTP_PORT`	HTTP API server port	`8000`

Data Storage

data/
├── speeches/           # Processed JSON documents
│   ├── fed-speech-xxx.json
│   └── ...
└── raw/               # Raw HTML content (for traceability)
    ├── 20240115_abc123.html
    └── ...

Development

Running Unit Tests

# Install with dev dependencies
uv sync --dev

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_models.py

# Run with coverage
uv run pytest --cov=fed_speech_mcp

Running Local Integration Tests

# Test all MCP functionality end-to-end
uv run python scripts/test_local.py all

# Test specific functionality
uv run python scripts/test_local.py refresh --limit 3
uv run python scripts/test_local.py search --query "rates"

Project Structure

fed-speech-mcp/
├── src/fed_speech_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server entry point
│   ├── http_server.py     # HTTP API wrapper
│   ├── config.py          # Configuration
│   ├── models/            # Pydantic data models
│   ├── ingestion/         # RSS/index discovery & fetching
│   ├── parsing/           # HTML parsing & normalization
│   ├── features/          # Feature extraction & scoring
│   └── storage/           # JSON storage layer
├── data/                  # Data directory
├── pyproject.toml
└── README.md

License

MIT

Acknowledgments

Data sourced from the Federal Reserve Board.