Add Sugra API plugin (sugra-systems)

.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."
     }
   ]
 }

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 `[email protected]` in the manifest).
 
 ## Repository structure

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": "[email protected]"
+  },
+  "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"
+}

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.

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: [email protected]
+
+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

third_party/sugra-systems/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sugra-api": {
+      "type": "http",
+      "url": "https://mcp.sugra.ai/mcp"
+    }
+  }
+}

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 [email protected] 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.

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.

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.