# PulseWatch public knowledge integration

For developers connecting an AI assistant to public PulseWatch information.
This service retrieves published facts; it is not an autonomous competitor analyst.
No account, API key, paid model or booking service is involved.

## Sources and freshness

- Human-readable index: https://pulsewatch.top/knowledge/
- Croatian index: https://pulsewatch.top/hr/znanje/
- JSON catalogue: https://pulsewatch.top/knowledge/catalog.json
- JSON Schema: https://pulsewatch.top/knowledge/catalog.schema.json
- English reading export: https://pulsewatch.top/knowledge/en.md
- Croatian reading export: https://pulsewatch.top/knowledge/hr.md
- Optional reading index: https://pulsewatch.top/llms.txt

The generator projects the same public PageSpec, OfferSpec and enforced watchlist
limits used by the website. The catalogue has a schema version, content revision,
canonical URLs and document content hashes. A hash identifies content, not a new
human review date or current capacity. Retrieve again when a source changes.
Preserve source URLs in downstream answers and label synthetic examples as such.

## Shared read-only actions

| Action | Arguments | Output |
|---|---|---|
| `list_offers` | `locale`: `en` (default) or `hr` | Prices, scope, conditions, written enquiry process and source URL |
| `search_knowledge` | `query`: 1–200 UTF-8 bytes; optional `locale`; `limit`: integer 1–5 (default 3) | Keyword matches, excerpts, document IDs and canonical URLs |
| `read_knowledge` | `id` returned by search | Complete published source text, URL and content hash |

Search is deterministic keyword matching, not semantic inference. Prefer concise
terms such as `pilot`, `pricing`, `cijene` or `tjedni brief`. A query with no match
returns an empty result, not an invented answer. Fetch the full document before
using an excerpt to advise a buyer. Both protocols call the same functions.

## MCP

Add the URL `https://pulsewatch.top/mcp/` to a client that supports remote
Streamable HTTP. No key is required for this public, read-only endpoint. Client
configuration UI and connector availability vary; no third-party listing is implied.

Supported wire revisions: `2026-07-28` and `2025-11-25`.
The current revision uses per-request metadata and `server/discover`; the older
revision uses `initialize` and `notifications/initialized`. No session ID is issued.
Responses are ordinary JSON. GET streams, subscriptions, prompts, sampling,
elicitation, task extensions and HTTP+SSE are not implemented.

Example for the current revision:

```sh
curl --fail-with-body https://pulsewatch.top/mcp/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: list_offers' \
  --data '{"jsonrpc":"2.0","id":"offers-1","method":"tools/call","params":{"name":"list_offers","arguments":{"locale":"hr"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
```

Expected: HTTP 200, `resultType: complete`, `isError: false`, three offers in
`structuredContent`, the catalogue revision and a canonical pricing source.
Use `tools/list` to discover exact schemas. `resources/list` exposes the JSON
catalogue and two Markdown exports; `resources/read` accepts only those exact URIs.

## A2A

- Discovery: `https://pulsewatch.top/.well-known/agent-card.json`
- Endpoint: `https://pulsewatch.top/a2a/`
- A2A version: `1.0`, using JSON-RPC **2.0**, PascalCase methods and ProtoJSON fields.
- Skill: `public-knowledge`. Streaming and push notifications are disabled.

```sh
curl --fail-with-body https://pulsewatch.top/a2a/ \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{"jsonrpc":"2.0","id":"offers-1","method":"SendMessage","params":{"message":{"messageId":"request-1","role":"ROLE_USER","parts":[{"data":{"action":"list_offers","arguments":{"locale":"hr"}}}]}}}'
```

Expected: HTTP 200 and a `result.message` with `ROLE_AGENT`, a context ID and
text/data parts containing the same sourced result as MCP.
For keyword search send one text part, such as `{"text":"pilot pricing"}`;
set `message.metadata.locale` to `hr` for Croatian (default `en`).
Only one text or structured data part is accepted per message. Files and URL parts
are rejected and never fetched. Subsequent requests may echo `contextId`, but
must include the full question/action: this service has no conversational memory.
No tasks are created; `ListTasks` is empty and task lookups fail as not found.
Repeated identical reads against the same revision return the same result/IDs.

## Errors, privacy and limits

- POST JSON bodies are limited to 8 KiB. GET returns 405; malformed requests 400;
  oversized bodies 413; unsupported request content type 415.
- Unsupported MCP revision: error `-32022` with supported versions. Header/body
  mismatch: `-32020`. Unsupported A2A revision: `-32009`.
- Invalid tool arguments are returned as MCP `isError: true`; unknown methods
  or resources never fall back to filesystem or network access.
- The endpoints are server-to-server. Cross-origin browser calls are not enabled;
  unexpected Origin/Host headers return 403. Do not remove these protections to
  work around a client configuration problem.
- Only the fixed public catalogue and its exports can be read. Request bodies
  are not stored by the application; web-server access metadata may be logged.
  Do not send personal data, client records, private watchlists or secrets.
- There are no enquiries, emails, purchases, bookings, competitor captures or
  approvals through these endpoints. A human reviews pilot fit and capacity
  through the ordinary written enquiry and email process.

## Hrvatski sažetak

AI asistent može pročitati pakete, pretražiti javne izvore i dohvatiti puni tekst
odabranog izvora. Parametar `locale: "hr"` bira hrvatski sadržaj. Nema pristupa
klijentskim podacima, slanja upita, telefonskih razgovora ni rezervacije kapaciteta.
Upit za stvarni pilot šalje se putem obrasca, a nastavak ide pisano emailom.

MCP, A2A i ovaj katalog omogućuju povezivanje kompatibilnih alata. Ne jamče
indeksiranje, citiranje ili preporuku u AI pretrazi.