diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 9b31a43f9..8fd6b8fb6 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -652,6 +652,11 @@ "name": "servicenow", "source": "third_party/servicenow", "description": "Call the tools your admin publishes on a ServiceNow instance." + }, + { + "name": "sugra-systems", + "source": "third_party/sugra-systems", + "description": "Query economic indicators, central banks, market data, filings, news, weather, and more, with sources cited." } ] } diff --git a/README.md b/README.md index 9d46b46a2..3f6f6167b 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `ringcentral-phone` | [RingCentral Phone](third_party/ringcentral-phone/) | Cursor | Integrations | Read call activity, AI call notes, SMS, voicemail, and fax, and send SMS. | | `ringcentral-chat` | [RingCentral Chat](third_party/ringcentral-chat/) | Cursor | Integrations | Read team chats and posts, send messages, and manage teams, tasks, and notes. | | `servicenow` | [ServiceNow](third_party/servicenow/) | Cursor | Integrations | Call the tools your admin publishes on a ServiceNow instance. | +| `sugra-systems` | [Sugra API](third_party/sugra-systems/) | Sugra Systems, Inc. | Integrations | Query economic indicators, central banks, market data, filings, news, weather, and more, with sources cited. | Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest). ## Repository structure diff --git a/third_party/sugra-systems/.cursor-plugin/plugin.json b/third_party/sugra-systems/.cursor-plugin/plugin.json new file mode 100644 index 000000000..596912c3a --- /dev/null +++ b/third_party/sugra-systems/.cursor-plugin/plugin.json @@ -0,0 +1,37 @@ +{ + "name": "sugra-systems", + "displayName": "Sugra API", + "version": "1.2.1", + "description": "Query economic indicators, central banks, market data, filings, news, weather, and more, with sources cited.", + "author": { + "name": "Sugra Systems, Inc.", + "email": "support@sugra.systems" + }, + "homepage": "https://sugra.systems", + "repository": "https://github.com/Sugra-Systems/sugra-api-plugins", + "license": "MIT", + "logo": "assets/logo.png", + "keywords": [ + "sugra", + "economic data", + "macroeconomics", + "central banks", + "market data", + "company filings", + "news", + "weather", + "climate", + "public data", + "mcp" + ], + "category": "integrations", + "tags": [ + "sugra", + "data", + "finance", + "economics", + "mcp" + ], + "skills": "./skills/", + "mcpServers": "./mcp.json" +} diff --git a/third_party/sugra-systems/LICENSE b/third_party/sugra-systems/LICENSE new file mode 100644 index 000000000..c8f12e437 --- /dev/null +++ b/third_party/sugra-systems/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Sugra Systems, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third_party/sugra-systems/README.md b/third_party/sugra-systems/README.md new file mode 100644 index 000000000..da831cea4 --- /dev/null +++ b/third_party/sugra-systems/README.md @@ -0,0 +1,64 @@ +# Sugra API + +Cursor plugin that connects agents to the [Sugra API](https://sugra.systems) through Sugra's hosted [Model Context Protocol](https://modelcontextprotocol.io/) server, plus skills for finding the right endpoint, calling it with the right parameters, and citing the source and date of every figure. + +Sugra API serves data from primary sources: economic indicators, central banks, market data, company filings, news, weather and climate, internet infrastructure, research datasets, and sanctions screening. + +## Install + +1. Open **Cursor Settings → Plugins**. +2. Search for **Sugra API**. +3. Click **Install**, then complete the Sugra sign-in prompt in your browser. + +Or run `/add-plugin sugra-systems` in chat. + +## MCP + +```json +{ + "mcpServers": { + "sugra-api": { + "type": "http", + "url": "https://mcp.sugra.ai/mcp" + } + } +} +``` + +Auth is OAuth 2.0. On first connect, Cursor opens the Sugra sign-in in the browser. If the server shows **Needs authentication**, open **Cursor Settings → Tools & MCPs**, find `sugra-api`, and select **Connect**. There is no API key to configure in the plugin. + +## Before you connect + +You need a Sugra account. A free account at [app.sugra.ai](https://app.sugra.ai) includes 50 requests a day. + +## Skills + +| Skill | Use | +| --- | --- | +| `using-sugra-api` | Map of the API, its product directions, and which skill to load next | +| `discover-and-call` | Find an operation, call it, and check the result answers the question | +| `envelope-and-attribution` | Parse responses and cite each figure's source and date | +| `auth-and-quota` | Keys, daily quota, and what to do on each error | +| `cross-domain-briefing` | Combine two or three directions in one answer | +| `live-docs` | Check current documentation when details may be stale | + +The hosted runtime is the source of truth for tool names and schemas. + +## Try it + +- "Compare US and Germany CPI inflation rates over the last 5 years." +- "What does the Fed funds rate look like, and when was the last policy change?" +- "What is the three-day weather forecast for Rotterdam?" + +## Docs + +- Documentation: https://docs.sugra.ai +- Server URL: https://mcp.sugra.ai/mcp +- Source: https://github.com/Sugra-Systems/sugra-api-plugins +- Support: support@sugra.systems + +The skills and logo are copied from the `cursor/` package in [Sugra-Systems/sugra-api-plugins](https://github.com/Sugra-Systems/sugra-api-plugins) at commit `4a6a636`. + +## License + +MIT diff --git a/third_party/sugra-systems/assets/logo.png b/third_party/sugra-systems/assets/logo.png new file mode 100644 index 000000000..0aa5175ab Binary files /dev/null and b/third_party/sugra-systems/assets/logo.png differ diff --git a/third_party/sugra-systems/mcp.json b/third_party/sugra-systems/mcp.json new file mode 100644 index 000000000..c57ab3ad3 --- /dev/null +++ b/third_party/sugra-systems/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "sugra-api": { + "type": "http", + "url": "https://mcp.sugra.ai/mcp" + } + } +} diff --git a/third_party/sugra-systems/skills/auth-and-quota/SKILL.md b/third_party/sugra-systems/skills/auth-and-quota/SKILL.md new file mode 100644 index 000000000..f86047960 --- /dev/null +++ b/third_party/sugra-systems/skills/auth-and-quota/SKILL.md @@ -0,0 +1,51 @@ +--- +name: auth-and-quota +description: Use a Sugra key, stay inside the daily quota, and act on each error over HTTPS or MCP. Use when the user needs a key, before a bulk call, or when a call returns 400, 401, 404, 422, 429, 5xx, missing_api_key, missing_bearer_token, unknown_parameters, needs_params, or upstream_*. +license: MIT +--- + +# Auth and quota + +One key. Volume gating only: every plan sees every endpoint. Plans and errors on https://docs.sugra.ai (search Authentication, Rate limits). + +Sign up at https://app.sugra.ai/register: a Free key is issued at signup. Keys: https://app.sugra.ai/developer/keys. Plans and prices: https://sugra.systems/api/pricing. Prefix `sugra_...`. Do not log the key, and do not put it in a skill file, a commit, or a chat. + +Free: 50 requests a day. Paid plans raise that volume; the volume and price of each plan are on the pricing page. + +The daily quota belongs to the account, not to one key: every key of the account draws on the same count. It resets at 00:00 UTC. + +A keyed data call costs at least 1 request. The public system endpoints (`/health`, `/sources`, `/openapi.json`) and the stdio catalog tools make no data call. Before a bulk call read MCP `describe_endpoint` `agent_hints.bulk_cost`. Over HTTPS, `X-RateLimit-Remaining` on each keyed response shows what is left. Over MCP, hosted composed tools report their own cost in `billing` (`rate_limit_cost`, `downstream_calls`, `remaining`), and one composed call can spend more than 1 request. + +## HTTPS API + +``` +x-api-key: sugra_... +``` + +On `https://sugra.ai` the key goes only in the `x-api-key` header. + +Keyed responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (the last second of the UTC quota day in ISO 8601, `YYYY-MM-DDT23:59:59Z`), and `X-Request-ID`. A 429 also carries `Retry-After` (seconds). + +## MCP + +How each MCP client signs in to the Sugra API MCP server: https://docs.sugra.ai/doc-2263382. + +MCP tool JSON does not forward `X-RateLimit-*`. Read an MCP error's `error` first, then follow its `hint` or `retry_hint` when it has one. When the API answered, the error has a numeric `status_code`, plus `request_id` (the API's `X-Request-ID`) and `retry_after` (seconds) when the API sent them. A network failure (`upstream_timeout`, `upstream_connect_error`, `upstream_transport_error`) has no HTTP status and carries a `reason`. An answer too large for MCP comes back trimmed with `meta.truncated`, or as `response_too_large`: narrow the filters. Catalog and validation errors (`unknown_parameters`, `missing_required_parameters`, `needs_params`, `missing_required_parameter_groups`, `unknown_operation_id`) make no API call and carry their own fields (table below). + +## Errors + +Read the message before anything else: it usually names the fix. + +| Signal | Meaning | What to do | +|---|---|---| +| HTTP 400 / 422 | a parameter is missing, malformed, or out of range | find which one in the message (over MCP a 422 can arrive as a bare `HTTP 422`: then check every parameter against `describe_endpoint`), fix it, then call again | +| MCP `unknown_parameters` (hosted server only) | a key the operation does not declare | use a name from `accepted` or `did_you_mean` | +| MCP `missing_required_parameters` / `needs_params` / `missing_required_parameter_groups` | required parameters are missing | fill them from the returned list, then call again | +| MCP `unknown_operation_id` | the id is not in the catalog | search again; do not guess an id | +| HTTP 404 | no such path, or no such item (an airport, a paper, a series) | if the message names a missing item, fix the input; otherwise check the path on docs.sugra.ai. Do not guess | +| HTTP 401 / MCP `missing_api_key` / `missing_bearer_token` | missing or invalid credential | stop. Do not retry the same call. Over MCP, point the user to the sign-in page in MCP above | +| HTTP 429 / MCP 429 | the account's quota is spent, or a short protective limit | wait for `Retry-After` / `retry_after`, or until `X-RateLimit-Reset`. On the hosted server a spent quota carries `reason: daily_limit_reached` (with `daily_limit` and `plan` when known): tell the user it resets at 00:00 UTC | +| MCP `server_busy` / `deadline_exceeded` | the MCP server is at its limit, or the call ran past its time budget | do what its `retry_hint` says | +| HTTP 5xx / MCP `upstream_*` | platform or upstream fault | if the message says the input does not exist (an unknown series or identifier), fix the input; otherwise retry once with backoff, then tell the user to write to support@sugra.systems with `X-Request-ID` / `request_id` when there is one, else with the whole error | + +Do not retry a 4xx unchanged. Retry a 429 only after the wait it names. diff --git a/third_party/sugra-systems/skills/cross-domain-briefing/SKILL.md b/third_party/sugra-systems/skills/cross-domain-briefing/SKILL.md new file mode 100644 index 000000000..f600f70e9 --- /dev/null +++ b/third_party/sugra-systems/skills/cross-domain-briefing/SKILL.md @@ -0,0 +1,25 @@ +--- +name: cross-domain-briefing +description: Compose one briefing from two or three Sugra directions over HTTPS or MCP. Use when a question spans Finance, Macro, Entity, Net Atlas, News, Earth, or Research and one operation is not enough. +license: MIT +--- + +# Cross-domain briefing + +Split the question. Call two or three operations. Do not invent a combined index. HTTP and MCP are both valid; use the surface already connected. Confirm each operation on https://docs.sugra.ai. + +## Pattern + +1. Split the question into 2-3 concrete asks (place, series, snapshot). Name the directions involved (Finance, Macro, Entity, Net Atlas, News, Earth, Research). +2. For each ask, discover then call (`discover-and-call`). Prefer sovereign or intergovernmental sources when the catalog offers them. +3. Keep units, geography, and clocks separate. Do not blend a port throughput z-score with a weather reading into one invented number. +4. Quote each figure with its source from `meta` (or `_meta` on a flat payload) and its date: an `as_of` when present (in a record, in `data`, or in `meta`), `meta.period`, or a `data_time` the source stated, never one that fell back to the response time. With none of them, say the source time is unavailable (see `envelope-and-attribution`). +5. Close with what the catalog did not cover, not a prediction. + +## Example shape (not a canned path list) + +"What is happening around a chokepoint this week?" can be three calls: port throughput (Sugra Earth / transport), conditions at a coordinate on the route (Sugra Earth), and one related sovereign or intergovernmental series docs.sugra.ai actually lists. Discover, call, present side by side. + +The MCP prompt `earth_conditions` is a one-coordinate recipe for weather, air quality, and nearby hazards. This skill is the longer form when those conditions are only one pane. + +Do not add per-endpoint MCP tools. Do not treat screening as a briefing source unless the question is about a named party. On MCP, stay on the gateway tools so the briefing works on stdio and hosted alike. Do not frame the output as investment, legal, or routing advice. diff --git a/third_party/sugra-systems/skills/discover-and-call/SKILL.md b/third_party/sugra-systems/skills/discover-and-call/SKILL.md new file mode 100644 index 000000000..7640321fd --- /dev/null +++ b/third_party/sugra-systems/skills/discover-and-call/SKILL.md @@ -0,0 +1,60 @@ +--- +name: discover-and-call +description: Find the right Sugra operation, call it over HTTPS or MCP, and check that the result answers the question. Use when the path or operation_id is unknown, before guessing parameters, before quoting a figure, or after a catalog miss. Confirm details on https://docs.sugra.ai. Do not invent routes. +license: MIT +--- + +# Discover and call + +Do not invent paths or `operation_id`s. Confirm the operation on https://docs.sugra.ai (search or Ask AI, then the endpoint page). Two complete loops, same API. + +## HTTP loop + +1. If the path is already known, skip to step 4 after confirming it on docs.sugra.ai. +2. Search https://docs.sugra.ai. Machine companion: `GET https://sugra.ai/openapi.json`. List of source names: `GET https://sugra.ai/sources`. +3. Read every parameter with its default and, for POST, the request body. Parameter names come from docs or the spec, spelled exactly: over HTTP most routes ignore an unknown query parameter without an error, so a misspelled filter (`country` for `countries`) returns the default data. +4. Call `https://sugra.ai` with `x-api-key`. Set every parameter the question names (place, identifier, period, frequency, unit). GET uses query params. POST uses JSON body plus any path or query params the spec lists. +5. Parse `{data, meta}`, or the flat object with `meta` / `_meta` that a few payloads return. Check the answer (below), then cite the source and the figure's date (check 4). Read `X-RateLimit-Remaining`. + +``` +GET https://sugra.ai/api/v1/etf/sectors/relative-strength?window=1m +x-api-key: sugra_... +``` + +## MCP loop + +Works on hosted and stdio. Do not call hosted-only names on stdio. The catalog tools (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) read the catalog bundled with the server and do not call https://sugra.ai; only `call_endpoint`, `fetch_data`, and the entity tools do. + +1. `search_endpoints(query=..., toolset=None, source=None, limit=10)`. Unknown `toolset` / `source` returns `unknown_toolset` / `unknown_source` with the valid set, not an empty hit list. +2. Pick an `operation_id` from `results` by its summary, not by its rank: the first hit is not always the measure asked for (a search for an unemployment rate can rank a labour force participation series first). Confirm it on docs.sugra.ai. +3. `describe_endpoint(operation_id=...)` - params with defaults, `request_body_schema` on POST, `agent_hints` (`duration_class`, `max_concurrency`, `bulk_cost`). +4. `call_endpoint(operation_id=..., params={...}, body=...)`. Set every parameter the question names. On the hosted server a key the operation does not declare returns `unknown_parameters` with `accepted` and, when close, `did_you_mean`. + +`fetch_data(query=...)` is a one-shot: it calls the top catalog match with the params given. A missing required parameter returns `needs_params` with the selected endpoint and candidates; a missing optional one silently takes its default. Check the answer below before using it; if the operation or the place is wrong, use the four-step loop. `list_toolsets` and `list_sources` (resources `sugra://catalog/domains`, `sugra://catalog/sources`) are the map, not the query. + +Shaping on `call_endpoint` / `fetch_data` (`limit`, `fields` as dotted paths, `include_raw`): skill `envelope-and-attribution`. + +Hosted only: `resolve_entity`, `get_snapshot`, `get_timeseries`. LEI/VAT and sanctions on every transport: `sugra_entity_lookup`, `sugra_entity_screen`. + +The MCP prompts (`market_snapshot`, `macro_briefing`, `sanctions_screening`, `sector_compare`, `earth_conditions`, `source_overview`) are numbered recipes over the gateway tools. They are not the catalog and do not cover every direction. For anything they do not name, use the loop above. + +## Check the answer before quoting it + +1. `meta.endpoint` is the operation you meant. +2. The place, entity, and period in `data` are the ones asked about, not a default. +3. The measure is the one asked about: a participation rate is not an unemployment rate, a level is not a change, a monthly figure is not an annual one. +4. The figure is dated by an `as_of` (in a record, in `data`, or in `meta`), by `meta.period`, or by a `data_time` the source stated, never by one that fell back to the response time. With none of them, say the source time is unavailable (skill `envelope-and-attribution`). + +If any check fails, fix the call. Do not present a near miss as the answer, and do not fill a gap from memory. + +## Misses and errors + +A miss is not "Sugra has no data". Search docs.sugra.ai. Widen the query. Drop a bad MCP `toolset`/`source` filter. If MCP search still misses, fetch live `/openapi.json` (the wheel catalog can lag), then HTTP-call if the spec has it. + +An error message usually names the fix: read it before retrying. A 400 or 422 over HTTPS names the parameter or value to change; over MCP a 422 can arrive as a bare `HTTP 422`. Full table: skill `auth-and-quota`. + +Do not add per-endpoint MCP tools to skip this loop. Do not skip `describe_endpoint` when the parameter list is unknown. + +## Timeouts + +30 seconds covers most GETs. Bulk or live-upstream POSTs can run longer. MCP `agent_hints.duration_class` is the budget hint. A timeout is not empty data. diff --git a/third_party/sugra-systems/skills/envelope-and-attribution/SKILL.md b/third_party/sugra-systems/skills/envelope-and-attribution/SKILL.md new file mode 100644 index 000000000..48d606eb7 --- /dev/null +++ b/third_party/sugra-systems/skills/envelope-and-attribution/SKILL.md @@ -0,0 +1,62 @@ +--- +name: envelope-and-attribution +description: Parse Sugra API payloads over HTTPS or MCP, keep source attribution, and tell observation time from request time. Use when reading a response, citing a figure, or shaping a large payload. +license: MIT +--- + +# Envelope and attribution + +The API is LLM-friendly: one JSON envelope `{data, meta}` on most payloads, and the envelope-less exceptions are named below. Envelope detail also lives on https://docs.sugra.ai. + +Most responses: + +```json +{ + "data": {}, + "meta": { + "endpoint": "/api/v1/...", + "data_time": "2026-06-12T19:30:00Z", + "response_time": "2026-06-12T19:30:01Z", + "provider": "Sugra API ...", + "source": "fred", + "attribution": "", + "cached": false + } +} +``` + +Always present: `endpoint` (the operation that answered), `data_time`, `response_time`, `provider`. Present when they apply: + +| Key | Meaning | +|---|---| +| `source` | the upstream source id; name it only when it is a sovereign, intergovernmental, or academic source (Attribution below) | +| `attribution` | a notice the source requires; repeat it word for word wherever the figure is shown | +| `period` | the unit of observation (for example `2026-Q1`) when `data_time` is the start of a period | +| `data_age_days` | days since a time the source itself stated; absent when the source gave only a date or period, or no readable time (Time below) | +| `cached` | served from the platform cache | +| `stale`, `stale_since` | the data is older than it should be; say so when quoting it | +| `fallback_used`, `fallback_chain` | a secondary source answered | +| `notes` | a data quality caveat; pass it on | + +Some payloads also carry a `license` inside `data`. Keep it with the figure. + +Some payloads are envelope-less (a flat object with `meta` or `_meta` on the same record). Provenance keys still apply. + +HTTP: this JSON body plus `X-RateLimit-*` headers. + +MCP: `call_endpoint` / `fetch_data` return the same payload (a top-level array is wrapped as `{data: ...}`). `limit` and `fields` shape the records list in `data`, and lists nested inside records are never truncated; `include_raw` attaches the complete original payload under `raw` when it fits the size cap. An object `data` without a records list, or an envelope-less object, counts as one record for `fields`, and `meta` / `_meta` stay. On the hosted server a projection that matches nothing removes nothing, and the records list can also be the one list inside an object `data`, when exactly one of `data`, `entries`, `events`, `history`, `items`, `observations`, `points`, `records`, `results`, `rows`, `series`, `timeseries` holds a list. Keys beside that list, such as `total` and `count`, stay unless a `fields` entry names a key of `data` itself, which projects `data` as one record instead. Stdio packages up to 0.12.0 do not look inside an object `data` for a records list and can return empty records when no field matches. `meta.shaped` reports `fields_applied`, `fields_unmatched`, `limit_applied` and, on the hosted server, `records_path`. + +`meta.shaped` reports what shaping actually did, not an echo of the request. On the hosted server `records_path` names the records list that `limit` bounded or that `fields` were matched against (for example `data.items`), even when no field matched, and is null when shaping used no records list. There `limit` keeps the newest end when every record carries one date or period key in one format and the list runs one way by it (the last N of an oldest-first list, the first N of a newest-first one), and otherwise the first N; `meta.shaped` then reports `order` (`asc`, `desc` or `unknown`) and `kept_end` (`newest` or `first`). When `records_path` is `data.*.observations` (several named sub-series side by side, each bounded on its own), `order` and `kept_end` are maps keyed by sub-series name. Before citing the latest figure from a bounded list, check that `kept_end` is `newest`, for a sub-series the value under its name. Stdio packages up to 0.12.0 keep the first N and report neither. + +## Time + +`data_time` in `meta` (or `_meta` on a flat payload) is the observation or publication time the source states for the data. When the source states no time, or one that cannot be read, `data_time` falls back to the HTTP response time (in `meta` it then equals `response_time`) and `data_age_days` is absent; for a time that cannot be read, `meta.notes` says so. That fallback is the time of the response, not of the data: never present it as the date of a figure, and if it is shown at all, label it the response time. When `meta.period` is present, `data_time` is the start of that period, not a moment of observation. An `as_of` in a record, in `data`, or in `meta` dates the figure itself: a period, a report or snapshot date, or a collection time. When an `as_of` differs from a `data_time` the source stated, quote both. When nothing dates the figure, say the source time is unavailable. Do not describe a delayed series as a live tick, and say so when `stale` is true. + +## Attribution + +Every figure needs a source and an as-of. Take the source from `meta` / `_meta`, and the date from an `as_of` wherever it sits, `meta.period`, or a `data_time` the source stated (Time above): name the source, give the date or period or say the source time is unavailable, and when `attribution` is present repeat it verbatim. Live list: https://sugra.ai/sources (MCP resource `sugra://attribution`). + +- Sovereign, intergovernmental, and academic sources are named openly (for example FRED, IMF, ECB, NOAA, World Bank, SEC EDGAR). +- Commercial upstreams appear under Sugra-branded wrappers (Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather). Cite the wrapper, not the vendor, even when `meta.source` carries the vendor's id; a required `attribution` notice is still repeated as given. + +This is data presentation, not investment, legal, or compliance advice. Screening tools return a signal, not a determination. diff --git a/third_party/sugra-systems/skills/live-docs/SKILL.md b/third_party/sugra-systems/skills/live-docs/SKILL.md new file mode 100644 index 000000000..3f8d12e89 --- /dev/null +++ b/third_party/sugra-systems/skills/live-docs/SKILL.md @@ -0,0 +1,47 @@ +--- +name: live-docs +description: Find current Sugra documentation. Use when an endpoint, parameter, default, or version might be stale. Canonical docs are https://docs.sugra.ai (search and Ask AI). Also OpenAPI, /sources, the blog, and MCP tools/list. +license: MIT +--- + +# Live docs + +https://docs.sugra.ai is the external documentation truth. It has search and Ask AI. Per-endpoint parameters, schemas, and examples live in its API Reference sidebar. This skill pack does not copy that catalog. + +## How to read docs.sugra.ai + +1. Open https://docs.sugra.ai (Welcome: directions, key, envelope, plans, MCP). +2. Search the docs site, or use Ask AI, for the operation or topic. +3. Open the endpoint page in API Reference before calling. Confirm method, path, parameters with their defaults, and body. +4. Pages have a Markdown version at the page URL plus `.md`, and https://docs.sugra.ai/llms.txt indexes them. Prefer those for a compact read. + +Do not invent a path. Do not treat this SKILL.md, a README, or a cookbook recipe as the operation list. + +## Machine companions (not a second docs site) + +| URL | Role | +|---|---| +| `GET https://sugra.ai/openapi.json` | HTTP contract for the call | +| `GET https://sugra.ai/sources` | live source names | +| `GET https://sugra.ai/health` | liveness | + +These need no key. Public copy uses hedges (1,600+ endpoints, 160+ sources, 36 domains); quote them as hedges, not as counts. The MCP wheel catalog can lag OpenAPI. If MCP search misses, search docs.sugra.ai, then OpenAPI, then say whether the operation exists. + +MCP once connected: `initialize` (`serverInfo.version`), `tools/list`, `prompts/list`, `resources/list`. + +## Other public surfaces (search these, not the open web first) + +| Where | What | +|---|---| +| https://sugra.ai | product | +| https://sugra.systems | company, legal, API marketing, direction pages | +| https://sugra.systems/blog | blog index; article also as `/{slug}.md`; `llms.txt` | +| https://app.sugra.ai | keys, usage, billing, playground | +| https://app.sugra.ai/register | sign up; a key is issued at signup | +| https://app.sugra.ai/developer/keys | manage keys | +| https://sugra.systems/api/pricing | plans and prices | +| https://docs.sugra.ai/doc-2444801 | ecosystem: MCP package, HTTP recipes, OpenBB provider | + +Legal: https://sugra.systems/terms-of-service and sibling policy pages. Contacts: `support@`, `legal@`, `privacy@`, `abuse@` sugra.systems. + +Source names: live `/sources`. Sovereign, intergovernmental, and academic names are open. Commercial upstreams appear as Sugra Finance, Sugra News, Sugra Crypto, Sugra Forex, Sugra Weather. diff --git a/third_party/sugra-systems/skills/using-sugra-api/SKILL.md b/third_party/sugra-systems/skills/using-sugra-api/SKILL.md new file mode 100644 index 000000000..3b2cf87b0 --- /dev/null +++ b/third_party/sugra-systems/skills/using-sugra-api/SKILL.md @@ -0,0 +1,50 @@ +--- +name: using-sugra-api +description: Work with the Sugra API over HTTPS and MCP. Use when the task needs Sugra data, a key, product directions (Finance, Macro, Entity, Net Atlas, News, Earth, Research), or which skill to load next. +license: MIT +--- + +# Using the Sugra API + +Sugra API is intelligence infrastructure: one HTTP API, one key, seven product directions. Domain-agnostic. Do not frame it through one vertical. + +The surface is LLM-friendly: one `x-api-key`, one JSON envelope `{data, meta}` on most payloads (a few are flat, with `meta` or `_meta` on the record; see envelope-and-attribution), MCP as the agent-native entry. Documentation truth is https://docs.sugra.ai (search and Ask AI). This skill is a map, not the catalog. + +These files are English. Reply in the user's language. + +Public hedge (not a live count): 1,600+ endpoints, 160+ primary sources, 36 domains. Quote these as "more than", never as an exact figure. The current operation list is `https://sugra.ai/openapi.json` (skill `live-docs`). + +## Two complete ways in + +| Surface | When | How | +|---|---|---| +| HTTPS `https://sugra.ai` | The agent can GET/POST | `x-api-key` on `/api/v1/...` | +| MCP | The host is an MCP client | the Sugra API MCP server; setup for each client: https://docs.sugra.ai/doc-2263382 | + +Both reach the same API. Use the surface the host already has, or the one the user named. Key: sign up at https://app.sugra.ai/register (a key is issued at signup), manage keys at https://app.sugra.ai/developer/keys. Free: 50 requests a day per account. Do not log the key. + +## Before quoting a figure + +A call that returns data is not yet an answer. Check that `meta.endpoint` is the operation meant, and that the place, entity, period, and measure in `data` are the ones the user asked about. An optional parameter left out takes its default, which can be another country or period; a required one must be set. Details: skill `discover-and-call`. + +## Seven directions (one key, one budget) + +| Direction | Coverage | +|---|---| +| Sugra Finance | Equities, fundamentals, filings, fixed income, derivatives, crypto, forex | +| Sugra Macro | Central banks, national statistics, FRED, IMF, World Bank, OECD | +| Sugra Entity | Company resolution, sanctions and watchlist screening, identifiers | +| Sugra Net Atlas | Internet infrastructure: ASNs, prefixes, IXPs, routing, DNS | +| Sugra News | Global news flow and event signals | +| Sugra Earth | Weather, hazards, energy, transport, air quality, climate | +| Sugra Research | Scientific, patent, and academic datasets | + +## Skill map + +| Need | Skill | +|---|---| +| Live docs, search, Ask AI, sources, blog | `live-docs` | +| Key, plans, quota, errors | `auth-and-quota` | +| Find, call, and check an operation (HTTP and MCP) | `discover-and-call` | +| Envelope, sources, clocks, MCP shaping | `envelope-and-attribution` | +| Two or three directions in one answer | `cross-domain-briefing` |