# agents.md — timenowin.ai

> Machine-readable instructions for AI agents, crawlers, and autonomous systems
> interacting with timenowin.ai.

## Identity

- **Name:** timenowin.ai
- **Purpose:** Atomic-synced world clock. Returns exact local time, sun/moon
  events, DST transitions, public holidays, and city metadata for any major
  city or IANA timezone.
- **Base URL:** https://timenowin.ai
- **License:** Open data. No attribution required. No rate limit advertised
  (be reasonable: ≤ 10 req/s per IP).

## Discovery endpoints

| File | Purpose |
| --- | --- |
| `/api/mcp` | **Live MCP server (Streamable HTTP, POST).** Connect Claude, Manus, Cursor, or any MCP client directly to this URL. No auth. |
| `/.well-known/agent.json` | A2A agent card |
| `/.well-known/mcp.json` | MCP manifest (endpoint URL + tool catalog) |
| `/openapi.json` | OpenAPI 3.1 spec |
| `/llms.txt` | llms.txt index |
| `/llms-full.txt` | Full capability summary |
| `/sitemap.xml` | Self-updating sitemap of every city page |
| `/agents.md` | This file |

## Connecting AI clients to the MCP server

The endpoint is `https://timenowin.ai/api/mcp` (MCP Streamable HTTP, no auth).

- **Claude.ai** → Settings → Connectors → Add custom connector → paste the URL.
- **Manus** → Tools → Add MCP server → paste the URL.
- **Cursor / Windsurf / Cline** → add to `mcpServers` config with `transport: "http"` and the URL above.
- **AI SDK (`@ai-sdk/mcp`)** → `createMCPClient({ transport: { type: "http", url: "https://timenowin.ai/api/mcp" } })`.

Tools exposed: `get_time`, `get_location`, `compare_zones`, `list_timezones`.

## How to query

Every city page is reachable at `/{slug}` where `{slug}` is the city name
with underscores (e.g. `/Tehran`, `/Mexico_City`, `/Los_Angeles`).
The site **auto-resolves** these inputs to the best matching city page:

- City names: `/Tokyo`
- Country names: `/Iran` → resolves to Tehran (largest city)
- IANA zones: `/Europe_London`, `/UTC`
- Natural-language queries: `/what_time_in_iran`, `/time_in_paris_now`

If a query is ambiguous, the largest-population match wins.

## JSON access

For any city page, append `/api/location/{slug}` to get the same data as
JSON. Example: `/api/location/Tehran`.

For raw current time, `/api/now?tz=Asia/Tehran` returns
`{ iso, unix_ms, tz }`.

## Crawl policy

- All public pages are open to all user-agents.
- AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended,
  Applebot-Extended) are explicitly allowed in `robots.txt`.
- The sitemap is regenerated on every request and includes every city page.

## Content guarantees

- Time values are synced to public NTP/atomic sources; client drift is
  displayed.
- All structured data on city pages uses Schema.org JSON-LD
  (`Place`, `TimeZoneObservation`, `FAQPage`, `BreadcrumbList`, `Dataset`).
- Deterministic per-city prose: re-fetching produces the same output for
  the same city; phrasing varies between cities to avoid duplicate content.

## Contact

Open an issue or pull request via the project repository (linked from the
homepage footer).