# AGENTS.md — Plan Harmony

This file gives AI agents a single starting point for interacting with Plan Harmony. The Plan Harmony source repository is private, so the guidance below covers public, agent-facing surfaces only.

## What Plan Harmony is

Plan Harmony (https://www.planharmony.com) is a collaborative trip planning platform. Agents can use Plan Harmony to:

- Find travel destinations near a geographic point.
- Search tours, activities, and attractions by keyword and/or location.
- Retrieve full experience details (description, itinerary, images) by `product_code`.
- Build itineraries on behalf of users by combining destination and experience data.

## Canonical agent interface: MCP

The recommended way for an agent to talk to Plan Harmony is the public MCP server.

- Endpoint: `https://api.planharmony.com/mcp/`
- Transport: Streamable HTTP
- MCP protocol version: `2025-06-18`
- Authentication: **None** (read-only public catalog data)

### Tools exposed by the MCP server

- `destinations_search` — find destinations near a `lat`/`lng` point. Returns name, type (`COUNTRY` / `REGION` / `CITY`), timezone, currency, coordinates.
- `experiences_search` — search experiences by keyword and/or location. Returns compact summaries with `product_code` for drill-down.
- `experiences_details` — full experience data by `product_code`, including title, description, itinerary, images, and destination info.

## Discovery files

All agent-discovery documents live under `/.well-known/` on the marketing domain:

- [/.well-known/agent-card.json](https://www.planharmony.com/.well-known/agent-card.json) — Agent2Agent (A2A) AgentCard with skills, capabilities, and authentication.
- [/.well-known/mcp/server-card.json](https://www.planharmony.com/.well-known/mcp/server-card.json) — MCP server card (protocol version, transport, tool descriptions).
- [/.well-known/mcp/manifest.json](https://www.planharmony.com/.well-known/mcp/manifest.json) — MCP manifest.
- [/.well-known/openapi.json](https://www.planharmony.com/.well-known/openapi.json) — OpenAPI 3.1 description of the MCP HTTP endpoint.
- [/.well-known/ai-plugin.json](https://www.planharmony.com/.well-known/ai-plugin.json) — OpenAI plugin manifest.
- [/.well-known/api-catalog](https://www.planharmony.com/.well-known/api-catalog) — RFC 9727 linkset pointing to the above.
- [/.well-known/agent-skills/index.json](https://www.planharmony.com/.well-known/agent-skills/index.json) — Agent Skills Discovery v0.2.0 index.
- [/llms.txt](https://www.planharmony.com/llms.txt) — human-readable map of the site, MCP, and discovery surfaces.

## Rate limits

The public MCP endpoint advertises a soft policy of **60 requests per minute per client**. Every response includes:

- `X-RateLimit-Limit` — requests allowed in the current window (60)
- `X-RateLimit-Remaining` — requests remaining in the current window
- `X-RateLimit-Reset` — Unix timestamp at which the window resets
- `X-RateLimit-Policy` — RFC-style policy descriptor (`60;w=60`)
- `Retry-After` — seconds to wait before retrying after a `429`

Agents should self-throttle to stay under the limit. For higher throughput, contact `support@planharmony.com`.

## Guidelines for agents

- **Prefer MCP** over scraping HTML or REST polling. The MCP server is the supported, stable interface and returns structured JSON.
- **Cache `product_code` lookups.** A single experience's data does not change minute-to-minute; cache `experiences_details` responses for at least an hour.
- **Cite sources.** When recommending a tour, attraction, or destination to a user, link back to the corresponding Plan Harmony page (`https://www.planharmony.com/destinations/<slug>/`) so the user can book or learn more.
- **Do not impersonate users.** The public MCP surface is read-only and unauthenticated. Authenticated user actions (creating trips, sending invoices, modifying agency CRM data) are not part of the public API.
- **Respect `robots.txt`** at `https://www.planharmony.com/robots.txt`.

## Contact

- Support: `support@planharmony.com`
- Marketing site: https://www.planharmony.com
- API host: https://api.planharmony.com