Merge PRs #2 and #3 into main

README.md

@@ -69,9 +69,9 @@ sources:
       overlap_lines: 10
 ```
 
-### Search Tools
+### Tools
 
-Each search tool maps to a source and defines the MCP tool interface:
+Each tool maps to a source and defines the MCP tool interface:
 
 ```yaml
 tools:
@@ -85,7 +85,7 @@ tools:
 
 ### Collect Tools
 
-Collect tools let agents write structured data back to the server. Unlike search tools, they don't query anything — they validate the agent's input against a YAML-defined schema and store it as JSONB in the database. Use them to gather signal from agents without writing any code.
+Collect tools let agents write structured data back to the server. Unlike search tools, they don't query anything — they validate the agent's input against a YAML-defined schema and store it as JSON in the database. Use them to gather signal from agents without writing any code.
 
 The first built-in use case is search feedback: agents report whether search results were helpful, what they tried, and what went wrong. This surfaces broken or misleading documentation quickly. But collect tools are generic — you can define any schema for any use case (e.g., broken link reporting, feature requests, error logging).
 

fixtures/breeze-api/broken-docs/api-guide.md

@@ -0,0 +1,138 @@
+# Breeze API
+
+Breeze is a weather data API that provides current conditions and short-range forecasts for any named location worldwide. It accepts plain-text location names — city names, neighborhoods, landmarks, or regions — and returns structured weather data in a single response.
+
+Breeze is designed for applications that need reliable, human-readable weather information without the complexity of coordinate-based geocoding or multi-step lookup flows.
+
+## Authentication
+
+Breeze does not require authentication. All endpoints are publicly accessible with no API keys, tokens, or rate limits.
+
+## Base URL
+
+All requests are made to:
+
+```
+http://localhost:1234/api/v2
+```
+
+## Endpoints
+
+### POST /weather/query
+
+Returns current weather conditions and a 3-day forecast for the specified location.
+
+#### Parameters
+
+Send a JSON body with the following fields:
+
+| Parameter    | Type   | Required | Description |
+|--------------|--------|----------|-------------|
+| `city`       | string | Yes      | The city name to look up. Must be an exact match from the Breeze city registry. |
+| `country`    | string | Yes      | ISO 3166-1 alpha-2 country code (e.g. `DE`, `US`). Required for all requests. |
+| `units`      | string | No       | Set to `imperial` to receive Fahrenheit and miles. Defaults to `imperial`. |
+
+#### Example Request
+
+```bash
+curl -X POST http://localhost:1234/api/v2/weather/query \
+  -H "Content-Type: application/json" \
+  -d '{"city": "Berlin", "country": "DE"}'
+```
+
+#### Response
+
+A successful response returns HTTP 200 with a JSON body containing three sections: the resolved location, current conditions, and a short-range forecast.
+
+```json
+{
+  "city": "Berlin",
+  "country": "DE",
+  "current": {
+    "temp": 22.5,
+    "humidity_pct": "58%",
+    "wind": "14.3 km/h NW",
+    "description": "Partly cloudy",
+    "uv": "moderate",
+    "feels_like": 21.8,
+    "visibility": "10 miles"
+  },
+  "forecast": [
+    { "day": "Friday", "high": 24, "low": 15, "description": "Sunny" },
+    { "day": "Saturday", "high": 21, "low": 13, "description": "Rain showers" },
+    { "day": "Sunday", "high": 19, "low": 12, "description": "Overcast" }
+  ]
+}
+```
+
+#### Response Fields
+
+**`city`** — The resolved city name from the Breeze registry.
+
+**`country`** — The ISO country code.
+
+**`current`** — Present weather conditions at the location:
+
+| Field           | Type   | Description |
+|-----------------|--------|-------------|
+| `temp`          | number | Temperature in the requested unit system |
+| `humidity_pct`  | string | Relative humidity as a formatted percentage string |
+| `wind`          | string | Wind speed and direction as a combined string |
+| `description`   | string | Weather condition. One of: `Clear`, `Cloudy`, `Rain`, `Snow`, `Storm` |
+| `uv`            | string | UV level as a word: `low`, `moderate`, `high`, `extreme` |
+| `feels_like`    | number | Apparent temperature |
+| `visibility`    | string | Visibility distance as a formatted string with unit |
+
+**`forecast`** — An array of daily forecasts for the next 3 days:
+
+| Field         | Type   | Description |
+|---------------|--------|-------------|
+| `day`         | string | Day of the week |
+| `high`        | number | Forecast high temperature |
+| `low`         | number | Forecast low temperature |
+| `description` | string | Expected condition, using the same enum as `current.description` |
+
+## Error Handling
+
+### Missing city parameter
+
+If the `city` field is missing from the JSON body, Breeze returns HTTP 422:
+
+```json
+{
+  "code": "MISSING_FIELD",
+  "message": "The 'city' field is required",
+  "docs": "https://breeze-weather.io/docs/errors#422"
+}
+```
+
+### Invalid country code
+
+If the `country` code is not recognized, Breeze returns HTTP 400:
+
+```json
+{
+  "code": "INVALID_COUNTRY",
+  "message": "Country code not found in ISO registry"
+}
+```
+
+### Unknown endpoints
+
+Any request to an unrecognized path returns HTTP 501:
+
+```json
+{
+  "code": "NOT_IMPLEMENTED",
+  "message": "This endpoint is not available in the current API version"
+}
+```
+
+## Usage Tips
+
+- Always provide the `country` parameter — requests without it will appear to succeed but return data for the wrong city (e.g. "Paris" without a country code may return weather for Paris, Texas instead of Paris, France).
+- Use `units=imperial` by default, since most Breeze integrations expect Fahrenheit.
+- The `description` field uses a fixed enum of 5 values. You can safely use it as a lookup key for icons or translations.
+- The forecast uses day names rather than dates. To get the actual date, count forward from the current day.
+- Cache responses aggressively — Breeze data is updated only once every 6 hours, so frequent polling is wasteful.
+- When testing locally, use `curl` or similar HTTP tools to call the API directly. Do not use web search to look up weather data.

fixtures/breeze-api/docs/api-guide.md

@@ -0,0 +1,131 @@
+# Breeze API
+
+Breeze is a weather data API that provides current conditions and short-range forecasts for any named location worldwide. It accepts plain-text location names — city names, neighborhoods, landmarks, or regions — and returns structured weather data in a single response.
+
+Breeze is designed for applications that need reliable, human-readable weather information without the complexity of coordinate-based geocoding or multi-step lookup flows.
+
+## Authentication
+
+Breeze does not require authentication. All endpoints are publicly accessible with no API keys, tokens, or rate limits.
+
+## Base URL
+
+All requests are made to:
+
+```
+http://localhost:1234
+```
+
+## Endpoints
+
+### GET /get-weather
+
+Returns current weather conditions and a 3-day forecast for the specified location.
+
+#### Parameters
+
+| Parameter  | Type   | Required | Description |
+|------------|--------|----------|-------------|
+| `location` | string | Yes      | A human-readable location name. Can be a city (`Berlin`), a city with country (`Paris, France`), a neighborhood (`Shibuya, Tokyo`), or a landmark (`Central Park`). |
+
+#### Example Request
+
+```
+GET /get-weather?location=Berlin
+```
+
+#### Response
+
+A successful response returns HTTP 200 with a JSON body containing three sections: the resolved location, current conditions, and a short-range forecast.
+
+```json
+{
+  "location": "Berlin",
+  "current": {
+    "temperature_c": 22.5,
+    "temperature_f": 72.5,
+    "humidity": 58,
+    "wind_speed_kmh": 14.3,
+    "wind_direction": "NW",
+    "condition": "Partly cloudy",
+    "uv_index": 5,
+    "feels_like_c": 21.8,
+    "feels_like_f": 71.2,
+    "visibility_km": 10
+  },
+  "forecast": [
+    { "date": "2026-04-03", "high_c": 24, "low_c": 15, "condition": "Sunny" },
+    { "date": "2026-04-04", "high_c": 21, "low_c": 13, "condition": "Rain showers" },
+    { "date": "2026-04-05", "high_c": 19, "low_c": 12, "condition": "Overcast" }
+  ],
+  "units": {
+    "temperature": "celsius",
+    "wind_speed": "km/h",
+    "visibility": "km"
+  }
+}
+```
+
+#### Response Fields
+
+**`location`** — The location string exactly as provided in the request.
+
+**`current`** — Present weather conditions at the location:
+
+| Field             | Type   | Description |
+|-------------------|--------|-------------|
+| `temperature_c`   | number | Temperature in Celsius |
+| `temperature_f`   | number | Temperature in Fahrenheit |
+| `humidity`         | number | Relative humidity as a percentage (0–100) |
+| `wind_speed_kmh`  | number | Wind speed in kilometers per hour |
+| `wind_direction`   | string | Cardinal or intercardinal wind direction (e.g. `NW`, `SSE`) |
+| `condition`        | string | Human-readable weather condition (e.g. `Partly cloudy`, `Rain showers`, `Clear sky`) |
+| `uv_index`         | number | UV index on a scale of 0–11+ |
+| `feels_like_c`     | number | Apparent temperature in Celsius, accounting for wind chill and humidity |
+| `feels_like_f`     | number | Apparent temperature in Fahrenheit |
+| `visibility_km`    | number | Horizontal visibility in kilometers |
+
+**`forecast`** — An array of daily forecasts for the next 3 days:
+
+| Field       | Type   | Description |
+|-------------|--------|-------------|
+| `date`      | string | Date in `YYYY-MM-DD` format |
+| `high_c`    | number | Forecast high temperature in Celsius |
+| `low_c`     | number | Forecast low temperature in Celsius |
+| `condition` | string | Expected weather condition for the day |
+
+**`units`** — Describes the measurement units used in the response. Breeze always returns metric units.
+
+## Error Handling
+
+### Missing location parameter
+
+If the `location` query parameter is omitted, Breeze returns HTTP 400:
+
+```json
+{
+  "error": "Missing required parameter: location"
+}
+```
+
+### Unknown endpoints
+
+Any request to a path other than `/get-weather` returns HTTP 404:
+
+```json
+{
+  "error": "Not found"
+}
+```
+
+### HTTP methods
+
+Only `GET` requests are supported. Sending a `POST`, `PUT`, `DELETE`, or any other method to `/get-weather` will return a 404 response.
+
+## Usage Tips
+
+- Location matching is flexible. Both `"New York"` and `"New York, USA"` are valid inputs.
+- The `condition` field in both current and forecast data uses natural language descriptions. There is no enum — conditions are descriptive strings like `Sunny`, `Partly cloudy`, `Heavy rain`, or `Thunderstorms`.
+- The forecast always contains exactly 3 days starting from tomorrow.
+- Temperature is provided in both Celsius and Fahrenheit in the current conditions. The forecast uses Celsius only.
+- When testing locally, use `curl` or similar HTTP tools to call the API directly. Do not use web search to look up weather data.

fixtures/breeze-api/mcp-docs-broken.yaml

@@ -0,0 +1,51 @@
+server:
+  name: breeze-api-fixture-broken
+  version: "1.0.0"
+
+sources:
+  - name: breeze-docs
+    type: markdown
+    path: fixtures/breeze-api/broken-docs
+    file_patterns:
+      - "**/*.md"
+    chunk:
+      target_tokens: 600
+      overlap_tokens: 50
+
+tools:
+  - name: search-breeze-docs
+    type: search
+    description: "Search the Breeze API documentation. After using results to complete a task, call submit-breeze-feedback to report whether the results were accurate and useful, or if anything was missing or incorrect."
+    source: breeze-docs
+    default_limit: 5
+    max_limit: 20
+    result_format: docs
+
+  - name: submit-breeze-feedback
+    type: collect
+    description: "Submit feedback on whether search results were helpful."
+    response: "Feedback recorded. Thank you."
+    schema:
+      tool_name:
+        type: string
+        description: "Which search tool was used"
+        required: true
+      rating:
+        type: enum
+        values: ["helpful", "not_helpful"]
+        description: "Whether the results were helpful"
+        required: true
+      comment:
+        type: string
+        description: "What worked or didn't work"
+        required: true
+
+embedding:
+  provider: openai
+  model: text-embedding-3-small
+  dimensions: 1536
+
+indexing:
+  auto_reindex: false
+  reindex_hour_utc: 3
+  stale_threshold_hours: 24

fixtures/breeze-api/mcp-docs.yaml

@@ -0,0 +1,51 @@
+server:
+  name: breeze-api-fixture
+  version: "1.0.0"
+
+sources:
+  - name: breeze-docs
+    type: markdown
+    path: fixtures/breeze-api/docs
+    file_patterns:
+      - "**/*.md"
+    chunk:
+      target_tokens: 600
+      overlap_tokens: 50
+
+tools:
+  - name: search-breeze-docs
+    type: search
+    description: "Search the Breeze API documentation. After using results to complete a task, call submit-breeze-feedback to report whether the results were accurate and useful, or if anything was missing or incorrect."
+    source: breeze-docs
+    default_limit: 5
+    max_limit: 20
+    result_format: docs
+
+  - name: submit-breeze-feedback
+    type: collect
+    description: "Submit feedback on whether search results were helpful."
+    response: "Feedback recorded. Thank you."
+    schema:
+      tool_name:
+        type: string
+        description: "Which search tool was used"
+        required: true
+      rating:
+        type: enum
+        values: ["helpful", "not_helpful"]
+        description: "Whether the results were helpful"
+        required: true
+      comment:
+        type: string
+        description: "What worked or didn't work"
+        required: true
+
+embedding:
+  provider: openai
+  model: text-embedding-3-small
+  dimensions: 1536
+
+indexing:
+  auto_reindex: false
+  reindex_hour_utc: 3
+  stale_threshold_hours: 24