mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
Two Windows agent-loop friction fixes: 1. tools/mcp_tool.py (#56536): shutil.which(cmd, path=env_path) reads executable extensions from the PARENT process PATHEXT, not the MCP subprocess env — a stdio MCP config supplying both PATH and PATHEXT could fail to resolve a command its own env can locate, and startup then got a bare command name. On Windows, when the first which() call misses and the config env carries PATHEXT (any key casing), retry the resolution with the config's PATHEXT temporarily applied. 2. skills/ + optional-skills/ (#50606): 42 SKILL.md files that declare platforms: [.., windows] used python3 in their command examples. python3 does not exist on native Windows (the toolchain probe in the system prompt reports python3=missing), so every copy-pasted example burned a failed agent turn before self-correction. Replaced the command word python3 -> python (python3-config / python3.x version strings untouched). python is the spelling that exists in every Hermes-managed environment (Windows native, uv-managed venvs on all three OSes); agents on POSIX hosts additionally see the probed toolchain line and adapt either way.
195 lines
6.5 KiB
Markdown
195 lines
6.5 KiB
Markdown
---
|
|
name: maps
|
|
description: "Geocode, POIs, routes, timezones via OpenStreetMap/OSRM."
|
|
version: 1.2.0
|
|
author: Mibayy
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
metadata:
|
|
hermes:
|
|
tags: [maps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm]
|
|
category: productivity
|
|
requires_toolsets: [terminal]
|
|
supersedes: [find-nearby]
|
|
---
|
|
|
|
# Maps Skill
|
|
|
|
Location intelligence using free, open data sources. 8 commands, 44 POI
|
|
categories, zero dependencies (Python stdlib only), no API key required.
|
|
|
|
Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
|
|
|
|
This skill supersedes the old `find-nearby` skill — all of find-nearby's
|
|
functionality is covered by the `nearby` command below, with the same
|
|
`--near "<place>"` shortcut and multi-category support.
|
|
|
|
## When to Use
|
|
|
|
- User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
|
|
- User wants coordinates for a place name → `search`
|
|
- User has coordinates and wants the address → `reverse`
|
|
- User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby`
|
|
- User wants driving/walking/cycling distance or travel time → `distance`
|
|
- User wants turn-by-turn directions between two places → `directions`
|
|
- User wants timezone information for a location → `timezone`
|
|
- User wants to search for POIs within a geographic area → `area` + `bbox`
|
|
|
|
## Prerequisites
|
|
|
|
Python 3.8+ (stdlib only — no pip installs needed).
|
|
|
|
Script path: `~/.hermes/skills/maps/scripts/maps_client.py`
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
MAPS=~/.hermes/skills/maps/scripts/maps_client.py
|
|
```
|
|
|
|
### search — Geocode a place name
|
|
|
|
```bash
|
|
python $MAPS search "Eiffel Tower"
|
|
python $MAPS search "1600 Pennsylvania Ave, Washington DC"
|
|
```
|
|
|
|
Returns: lat, lon, display name, type, bounding box, importance score.
|
|
|
|
### reverse — Coordinates to address
|
|
|
|
```bash
|
|
python $MAPS reverse 48.8584 2.2945
|
|
```
|
|
|
|
Returns: full address breakdown (street, city, state, country, postcode).
|
|
|
|
### nearby — Find places by category
|
|
|
|
```bash
|
|
# By coordinates (from a Telegram location pin, for example)
|
|
python $MAPS nearby 48.8584 2.2945 restaurant --limit 10
|
|
python $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
|
|
|
|
# By address / city / zip / landmark — --near auto-geocodes
|
|
python $MAPS nearby --near "Times Square, New York" --category cafe
|
|
python $MAPS nearby --near "90210" --category pharmacy
|
|
|
|
# Multiple categories merged into one query
|
|
python $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10
|
|
```
|
|
|
|
46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house,
|
|
camp_site, supermarket, atm, gas_station, parking, museum, park, school,
|
|
university, bank, police, fire_station, library, airport, train_station,
|
|
bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym,
|
|
swimming_pool, post_office, convenience_store, bakery, bookshop, laundry,
|
|
car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground,
|
|
stadium, nightclub.
|
|
|
|
Each result includes: `name`, `address`, `lat`/`lon`, `distance_m`,
|
|
`maps_url` (clickable Google Maps link), `directions_url` (Google Maps
|
|
directions from the search point), and promoted tags when available —
|
|
`cuisine`, `hours` (opening_hours), `phone`, `website`.
|
|
|
|
### distance — Travel distance and time
|
|
|
|
```bash
|
|
python $MAPS distance "Paris" --to "Lyon"
|
|
python $MAPS distance "New York" --to "Boston" --mode driving
|
|
python $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking
|
|
```
|
|
|
|
Modes: driving (default), walking, cycling. Returns road distance, duration,
|
|
and straight-line distance for comparison.
|
|
|
|
### directions — Turn-by-turn navigation
|
|
|
|
```bash
|
|
python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
|
|
python $MAPS directions "JFK Airport" --to "Times Square" --mode driving
|
|
```
|
|
|
|
Returns numbered steps with instruction, distance, duration, road name, and
|
|
maneuver type (turn, depart, arrive, etc.).
|
|
|
|
### timezone — Timezone for coordinates
|
|
|
|
```bash
|
|
python $MAPS timezone 48.8584 2.2945
|
|
python $MAPS timezone 35.6762 139.6503
|
|
```
|
|
|
|
Returns timezone name, UTC offset, and current local time.
|
|
|
|
### area — Bounding box and area for a place
|
|
|
|
```bash
|
|
python $MAPS area "Manhattan, New York"
|
|
python $MAPS area "London"
|
|
```
|
|
|
|
Returns bounding box coordinates, width/height in km, and approximate area.
|
|
Useful as input for the bbox command.
|
|
|
|
### bbox — Search within a bounding box
|
|
|
|
```bash
|
|
python $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20
|
|
```
|
|
|
|
Finds POIs within a geographic rectangle. Use `area` first to get the
|
|
bounding box coordinates for a named place.
|
|
|
|
## Working With Telegram Location Pins
|
|
|
|
When a user sends a location pin, the message contains `latitude:` and
|
|
`longitude:` fields. Extract those and pass them straight to `nearby`:
|
|
|
|
```bash
|
|
# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
|
|
python $MAPS nearby 36.17 -115.14 cafe --radius 1500
|
|
```
|
|
|
|
Present results as a numbered list with names, distances, and the
|
|
`maps_url` field so the user gets a tap-to-open link in chat. For "open
|
|
now?" questions, check the `hours` field; if missing or unclear, verify
|
|
with `web_search` since OSM hours are community-maintained and not always
|
|
current.
|
|
|
|
## Workflow Examples
|
|
|
|
**"Find Italian restaurants near the Colosseum":**
|
|
1. `nearby --near "Colosseum Rome" --category restaurant --radius 500`
|
|
— one command, auto-geocoded
|
|
|
|
**"What's near this location pin they sent?":**
|
|
1. Extract lat/lon from the Telegram message
|
|
2. `nearby LAT LON cafe --radius 1500`
|
|
|
|
**"How do I walk from hotel to conference center?":**
|
|
1. `directions "Hotel Name" --to "Conference Center" --mode walking`
|
|
|
|
**"What restaurants are in downtown Seattle?":**
|
|
1. `area "Downtown Seattle"` → get bounding box
|
|
2. `bbox S W N E restaurant --limit 30`
|
|
|
|
## Pitfalls
|
|
|
|
- Nominatim ToS: max 1 req/s (handled automatically by the script)
|
|
- `nearby` requires lat/lon OR `--near "<address>"` — one of the two is needed
|
|
- OSRM routing coverage is best for Europe and North America
|
|
- Overpass API can be slow during peak hours; the script automatically
|
|
falls back between mirrors (overpass-api.de → overpass.kumi.systems)
|
|
- `distance` and `directions` use `--to` flag for the destination (not positional)
|
|
- If a zip code alone gives ambiguous results globally, include country/state
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
python ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
|
|
# Should return lat ~40.689, lon ~-74.044
|
|
|
|
python ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
|
|
# Should return a list of restaurants within ~500m of Times Square
|
|
```
|