ai-agent-book/chapter4/perception-tools/CHANGES.md

Perception Tools - Updates & Changes

Summary

Updated the Perception Tools MCP Server to use 100% free, open APIs that require no API keys. This makes the tool immediately usable without any setup or registration.

Changes Made

1. Weather API - Replaced OpenWeather with Open-Meteo

Previous: OpenWeather API (required API key) New: Open-Meteo (free, no API key required)

Benefits:

• No registration or API key needed
• Automatic geocoding of city names
• High-quality weather data from national weather services
• Hourly resolution with up to 16-day forecasts
• 80 years of historical weather data available

Implementation:

• get_weather(location, latitude=None, longitude=None)
• Automatically geocodes location names to coordinates
• Returns temperature, humidity, wind speed, precipitation, and weather description

---

2. Web Search - Replaced Google Custom Search with DuckDuckGo

Previous: Google Custom Search API (required API key and CSE ID) New: DuckDuckGo HTML search (free, no API key required)

Benefits:

• No registration or API key needed
• Privacy-focused search engine
• Clean, ad-free results
• No usage limits

Implementation:

• search_web(query, num_results=5, region="wt-wt")
• Scrapes DuckDuckGo HTML results
• Returns title, URL, and snippet for each result

---

3. Cryptocurrency Prices - NEW TOOL ✨

API: CoinGecko (free, no API key required)

Features:

• Real-time cryptocurrency prices
• Support for 15+ major cryptocurrencies (BTC, ETH, SOL, etc.)
• Market cap, 24h volume, and price change data
• Multi-currency support (USD, EUR, GBP, etc.)

Implementation:

• get_crypto_price(symbol, vs_currency="usd")
• Maps common symbols (btc → bitcoin, eth → ethereum)
• Returns comprehensive price and market data

Example:

result = await get_crypto_price("btc", "usd")
# Returns: BTC price, market cap, 24h volume, 24h change

---

4. Location Search - NEW TOOL ✨

API: Nominatim (OpenStreetMap) (free, no API key required)

Features:

• Geocode any location worldwide
• Search landmarks, cities, addresses
• Detailed address information
• Country filtering option

Implementation:

• search_location(query, limit=5, country_code=None)
• Returns latitude, longitude, and detailed address
• Importance ranking for result relevance

Example:

result = await search_location("Eiffel Tower")
# Returns: coordinates, full address, location type

---

5. Point of Interest (POI) Search - NEW TOOL ✨

API: Overpass API (OpenStreetMap) (free, no API key required)

Features:

• Find restaurants, cafes, hotels, ATMs, hospitals, etc.
• Search within specified radius
• Rich metadata (phone, website, opening hours, cuisine)
• Worldwide coverage from OpenStreetMap data

Implementation:

• search_poi(query, latitude, longitude, radius=1000, limit=10)
• Searches for amenities, shops, tourism POIs
• Returns name, type, coordinates, and metadata

Example:

result = await search_poi("restaurant", 48.8584, 2.2945, radius=500)
# Returns: nearby restaurants with details

---

Existing Free APIs (Already Implemented)

These tools were already using free APIs:

1. Stock Prices - Yahoo Finance (free, no API key)
2. Currency Conversion - ExchangeRate-API (free, no API key)
3. Wikipedia - Wikipedia API (free, no API key)
4. ArXiv - ArXiv API (free, no API key)
5. Wayback Machine - Internet Archive (free, no API key)

---

Complete List of Free Tools

🔍 Search & Discovery

• ✅ Web Search (DuckDuckGo)
• ✅ Knowledge Base Search
• ✅ Wikipedia Search
• ✅ ArXiv Search
• ✅ Location Search (OpenStreetMap)
• ✅ POI Search (OpenStreetMap)

🌐 Public Data

• ✅ Weather (Open-Meteo)
• ✅ Stock Prices (Yahoo Finance)
• ✅ Crypto Prices (CoinGecko)
• ✅ Currency Conversion (ExchangeRate-API)

📄 Content Processing

• ✅ Web Page Reader
• ✅ Document Reader (PDF, DOCX, PPTX)
• ✅ File Operations
• ✅ Grep Search

🕰️ Historical Data

• ✅ Wayback Machine

---

Testing

All new and updated tools have been tested and verified:

# Test original tools
python quickstart.py

# Test new tools
python test_new_tools.py

All tests pass successfully with no API keys required!

---

Documentation Updates

• ✅ Updated README.md with new tool descriptions
• ✅ Updated env.example to reflect free APIs
• ✅ Added comprehensive parameter documentation
• ✅ Highlighted "No API Keys Required" throughout

---

Benefits of These Changes

1. Zero Setup - Works immediately after pip install -r requirements.txt
2. No Cost - All APIs are free for reasonable use
3. No Registration - No need to sign up or manage API keys
4. Privacy - DuckDuckGo and OpenStreetMap don't track users
5. Production Ready - APIs are stable and well-maintained
6. Global Coverage - Weather, maps, and location data worldwide

---

API Sources & Links

Tool	API Provider	Documentation
Weather	Open-Meteo	https://open-meteo.com/
Web Search	DuckDuckGo	https://duckduckgo.com/
Crypto Prices	CoinGecko	https://www.coingecko.com/en/api
Location Search	Nominatim (OSM)	https://nominatim.openstreetmap.org/
POI Search	Overpass API (OSM)	https://overpass-api.de/
Stock Prices	Yahoo Finance	https://finance.yahoo.com/
Currency	ExchangeRate-API	https://www.exchangerate-api.com/
Wikipedia	Wikipedia API	https://www.mediawiki.org/wiki/API
ArXiv	ArXiv API	https://arxiv.org/help/api

---

Acknowledgments

Special thanks to:

• Open-Meteo for providing free, high-quality weather data
• OpenStreetMap community for maintaining global map data
• CoinGecko for free cryptocurrency market data
• DuckDuckGo for privacy-respecting search

---

Next Steps

Potential future enhancements:

• Add rate limiting to respect API usage policies
• Implement caching for frequently accessed data
• Add more cryptocurrency exchanges
• Support for reverse geocoding
• Route planning with OpenStreetMap