hubris-mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,118 +1,131 @@
-# Hubris MCP
-
-[Model Context Protocol](https://modelcontextprotocol.io) server for [Hubris](https://hubris.pw) — an OpenAI-compatible LLM gateway with billing in rubles. Connect Claude Desktop, Claude Code, Cline, Cursor or any other MCP client to a single hosted server and get access to the model catalog, account balance and chat completions.
-
-There are two ways in: connect your client straight to the hosted endpoint, or run the stdio server in this repository, which declares the same tools locally and forwards calls to that endpoint. The second is what you want for clients that speak stdio only, and for sandboxes that build from a Dockerfile.
-
-Listing the tools needs no credential; only calling one does.
-
-- **Endpoint:** `https://api.hubris.pw/mcp`
-- **Transport:** Streamable HTTP
-- **Auth:** Bearer API key (`sk-gw-...`, create one at [hubris.pw/keys](https://hubris.pw/keys))
-- **Full docs:** [hubris.pw/docs/integrations/mcp](https://hubris.pw/docs/integrations/mcp)
-
-## Tools
-
-| Tool | Description |
-| --- | --- |
-| `models_list` | Full catalog of active models, cursor-paginated. |
-| `models_search` | Filter by capability (vision / reasoning / tools / web_search / audio_in / audio_out / image_gen / transcription), price, context length. |
-| `models_get_pricing` | Pricing for a specific model, in rubles. |
-| `balance_get` | Current account balance. |
-| `chat_complete` | LLM chat request — full parity with `POST /v1/chat/completions`. |
-
-## Resources
-
-| URI | Content |
-| --- | --- |
-| `hubris://catalog/models` | Full model catalog as a single JSON document. |
-| `hubris://docs/quickstart` | Quickstart page. |
-
-## Prompts
-
-- `compare-models {task}` — ready-made prompt for comparing models for a given task.
-
-## Run locally (stdio)
-
-```bash
-npm install && npm run build
-HUBRIS_API_KEY=sk-gw-... node dist/index.js
-```
-
-Or with Docker:
-
-```bash
-docker build -t hubris-mcp .
-docker run -i --rm -e HUBRIS_API_KEY=sk-gw-... hubris-mcp
-```
-
-In an MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "hubris": {
-      "command": "node",
-      "args": ["/path/to/hubris-mcp/dist/index.js"],
-      "env": { "HUBRIS_API_KEY": "sk-gw-..." }
-    }
-  }
-}
-```
-
-`HUBRIS_MCP_URL` overrides the endpoint if you need to point it elsewhere.
-
-## Connect
-
-### Claude Code
-
-```bash
-claude mcp add --transport http hubris https://api.hubris.pw/mcp \
-  --header "Authorization: Bearer sk-gw-..."
-```
-
-### Claude Desktop
-
-Claude Desktop only speaks stdio, so remote HTTP servers go through the [`mcp-remote`](https://github.com/geelen/mcp-remote) shim. Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "hubris": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "mcp-remote",
-        "https://api.hubris.pw/mcp",
-        "--transport",
-        "http-only",
-        "--header",
-        "Authorization:${AUTH_TOKEN}"
-      ],
-      "env": {
-        "AUTH_TOKEN": "Bearer sk-gw-..."
-      }
-    }
-  }
-}
-```
-
-### Cline / Cursor / other clients
-
-Any MCP client with Streamable HTTP transport support:
-
-| Field | Value |
-| --- | --- |
-| Transport | Streamable HTTP |
-| URL | `https://api.hubris.pw/mcp` |
-| Auth header | `Authorization: Bearer sk-gw-...` |
-
-Full connection guide (with client-specific caveats): [hubris.pw/docs/integrations/mcp](https://hubris.pw/docs/integrations/mcp).
-
-## Security
-
-The Bearer key grants access to your account balance. We recommend creating a dedicated key for MCP at [hubris.pw/keys](https://hubris.pw/keys) so it can be revoked independently of other integrations.
-
-## About Hubris
-
-Hubris is an OpenAI-compatible LLM gateway for the Russian market — one API key, one ruble-denominated balance, 400+ models. [hubris.pw](https://hubris.pw)
+# Hubris MCP
+
+[![smithery badge](https://smithery.ai/badge/hubris/hubris-mcp)](https://smithery.ai/servers/hubris/hubris-mcp) [![npm](https://img.shields.io/npm/v/hubris-mcp)](https://www.npmjs.com/package/hubris-mcp)
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [Hubris](https://hubris.pw) — an OpenAI-compatible LLM gateway with billing in rubles. Connect Claude Desktop, Claude Code, Cline, Cursor or any other MCP client to a single hosted server and get access to the model catalog, account balance and spending, and every kind of model in it: text, embeddings, rerankers, decision models, images, speech, transcription, video and YouTube transcripts.
+
+There are two ways in: connect your client straight to the hosted endpoint, or run the stdio server in this repository, which declares the same tools locally and forwards calls to that endpoint. The second is what you want for clients that speak stdio only, and for sandboxes that build from a Dockerfile.
+
+Listing the tools needs no credential; only calling one does. With `HUBRIS_API_KEY` set, the stdio server takes the tool list live from the hosted endpoint, so it never lags behind new tools; without a key it serves the list bundled with the package.
+
+- **Endpoint:** `https://api.hubris.pw/mcp`
+- **Transport:** Streamable HTTP
+- **Auth:** Bearer API key (`sk-gw-...`, create one at [hubris.pw/keys](https://hubris.pw/keys))
+- **Full docs:** [hubris.pw/docs/integrations/mcp](https://hubris.pw/docs/integrations/mcp)
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `models_list` | Full catalog of active models, cursor-paginated. |
+| `models_search` | Filter by the tool that runs the model (`tool`), capability, price, context length. |
+| `models_get_pricing` | Pricing for a specific model, in rubles; voices for speech models, durations and resolutions for video models. |
+| `balance_get` | Current account balance. |
+| `usage_get` | Spending over a period: requests, tokens, rubles. |
+| `chat_complete` | LLM chat request — same as `POST /v1/chat/completions`. |
+| `embeddings_create` | Embedding vectors — `POST /v1/embeddings`. |
+| `rerank` | Order documents by relevance to a query — `POST /v1/rerank`. |
+| `decisions_ask` | Yes/no, choice and scale answers with probabilities — `POST /v1/decisions`. |
+| `image_generate` | Draw an image, returned as image content — `POST /v1/images/generations`. |
+| `speech_create` | Text to speech, returned as audio content — `POST /v1/audio/speech`. |
+| `transcription_create` | Speech to text from base64 audio — `POST /v1/audio/transcriptions`. |
+| `video_create` | Start a video generation — `POST /v1/videos`. |
+| `video_get` | Status of a video task; download links once it is ready — `GET /v1/videos/{id}`. |
+| `youtube_transcribe` | Transcript or summary of a YouTube video — `POST /v1/video/transcriptions`. |
+
+## Resources
+
+| URI | Content |
+| --- | --- |
+| `hubris://catalog/models` | Full model catalog as a single JSON document. |
+| `hubris://docs/quickstart` | Quickstart page. |
+| `hubris://videos/{id}/content` | A finished video, linked from `video_get` (hosted endpoint only). |
+
+## Prompts
+
+- `compare-models {task}` — ready-made prompt for comparing models for a given task.
+
+## Run locally (stdio)
+
+```bash
+npm install && npm run build
+HUBRIS_API_KEY=sk-gw-... node dist/index.js
+```
+
+Or with Docker:
+
+```bash
+docker build -t hubris-mcp .
+docker run -i --rm -e HUBRIS_API_KEY=sk-gw-... hubris-mcp
+```
+
+In an MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "hubris": {
+      "command": "node",
+      "args": ["/path/to/hubris-mcp/dist/index.js"],
+      "env": { "HUBRIS_API_KEY": "sk-gw-..." }
+    }
+  }
+}
+```
+
+`HUBRIS_MCP_URL` overrides the endpoint if you need to point it elsewhere.
+
+## Connect
+
+### Claude Code
+
+```bash
+claude mcp add --transport http hubris https://api.hubris.pw/mcp \
+  --header "Authorization: Bearer sk-gw-..."
+```
+
+### Claude Desktop
+
+Claude Desktop only speaks stdio, so remote HTTP servers go through the [`mcp-remote`](https://github.com/geelen/mcp-remote) shim. Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hubris": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://api.hubris.pw/mcp",
+        "--transport",
+        "http-only",
+        "--header",
+        "Authorization:${AUTH_TOKEN}"
+      ],
+      "env": {
+        "AUTH_TOKEN": "Bearer sk-gw-..."
+      }
+    }
+  }
+}
+```
+
+### Cline / Cursor / other clients
+
+Any MCP client with Streamable HTTP transport support:
+
+| Field | Value |
+| --- | --- |
+| Transport | Streamable HTTP |
+| URL | `https://api.hubris.pw/mcp` |
+| Auth header | `Authorization: Bearer sk-gw-...` |
+
+Full connection guide (with client-specific caveats): [hubris.pw/docs/integrations/mcp](https://hubris.pw/docs/integrations/mcp).
+
+## Security
+
+The Bearer key grants access to your account balance. We recommend creating a dedicated key for MCP at [hubris.pw/keys](https://hubris.pw/keys) so it can be revoked independently of other integrations.
+
+## About Hubris
+
+Hubris is an OpenAI-compatible LLM gateway for the Russian market — one API key, one ruble-denominated balance, 400+ models. [hubris.pw](https://hubris.pw)

package/dist/index.js

@@ -6,9 +6,11 @@
  * package is the local end of that: it declares the tool surface and forwards
  * calls to https://api.hubris.pw/mcp with the caller's key.
  *
- * The declaration is deliberately local rather than proxied. A client — or a
- * directory's introspection crawler — can list the tools and read their
- * schemas without any credential; only an actual call needs HUBRIS_API_KEY.
+ * With a key, the tool list comes live from the hosted server, so the package
+ * never lags behind new tools. Without one — or if the server cannot be
+ * reached — the list bundled with this version is served, so a client or a
+ * directory's introspection crawler can read the tools and their schemas
+ * without any credential. Only an actual call needs HUBRIS_API_KEY.
  *
  * Configuration:
  *   HUBRIS_API_KEY   required to call a tool, not to list them
@@ -19,34 +21,20 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { TOOLS } from './tools.js';
 const ENDPOINT = process.env.HUBRIS_MCP_URL ?? 'https://api.hubris.pw/mcp';
-const PACKAGE_VERSION = '0.1.0';
-const INSTRUCTIONS = `Hubris is an OpenAI-compatible LLM gateway for the Russian market. It puts around 550 models from every major vendor behind one API billed in rubles, and this server exposes that catalogue, the account balance and the models themselves.
-
-The usual order of work:
-1. models_search — narrow the catalogue by capability, price ceiling and context window.
-2. models_get_pricing — confirm what the chosen model actually costs.
-3. chat_complete — run the request on it.
-balance_get shows what is left on the account; check it before a long run.
-
-Two things to keep in mind. Model ids are matched exactly and always carry the vendor prefix, as in "anthropic/claude-sonnet-5" — short names and names with a trailing date are rejected. And a "0.00" token price does not mean free: models billed per image, per second or per thousand characters report zero token rates, and their real price is in models_get_pricing under perUnit. The isFree flag is the only reliable answer to "is this free".
-
-Everything except chat_complete is read-only. chat_complete spends money from the account.`;
-/** Forwards one tools/call to the hosted server and returns its result. */
-async function callRemote(name, args) {
-    const apiKey = process.env.HUBRIS_API_KEY;
-    if (!apiKey) {
-        return {
-            isError: true,
-            content: [
-                {
-                    type: 'text',
-                    text: 'HUBRIS_API_KEY is not set. Create a key at https://hubris.pw/keys and pass it ' +
-                        'to this server through the environment. Listing tools works without one; ' +
-                        'calling them does not.',
-                },
-            ],
-        };
-    }
+const PACKAGE_VERSION = '0.2.0';
+const INSTRUCTIONS = `Hubris is an OpenAI-compatible LLM gateway for the Russian market. It puts around 550 models from every major vendor behind one API billed in rubles, and this server exposes that catalogue, the account balance and the models themselves.
+
+The usual order of work:
+1. models_search — narrow the catalogue by the tool that runs the model, capability, price ceiling and context window. Every model in the answer names its \`tool\`.
+2. models_get_pricing — confirm what the chosen model actually costs, and for speech and video models which voices or durations it takes.
+3. Run the request with that tool: chat_complete for text, embeddings_create, rerank, decisions_ask, image_generate, speech_create, transcription_create, video_create (then poll video_get) or youtube_transcribe.
+balance_get shows what is left on the account and usage_get what has been spent; check them before and after a long run.
+
+Two things to keep in mind. Model ids are matched exactly and always carry the vendor prefix, as in "anthropic/claude-sonnet-5" — short names and names with a trailing date are rejected. And a "0.00" token price does not mean free: models billed per image, per second or per thousand characters report zero token rates, and their real price is in models_get_pricing under perUnit. The isFree flag is the only reliable answer to "is this free".
+
+Tools that run a model spend money from the account; the catalogue, balance_get, usage_get and video_get only read.`;
+/** One JSON-RPC request to the hosted server. Throws with a readable reason. */
+async function rpc(apiKey, method, params) {
     let response;
     try {
         response = await fetch(ENDPOINT, {
@@ -56,25 +44,16 @@ async function callRemote(name, args) {
                 'content-type': 'application/json',
                 accept: 'application/json, text/event-stream',
             },
-            body: JSON.stringify({
-                jsonrpc: '2.0',
-                id: 1,
-                method: 'tools/call',
-                params: { name, arguments: args ?? {} },
-            }),
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
         });
     }
     catch (cause) {
         const reason = cause instanceof Error ? cause.message : String(cause);
-        return { isError: true, content: [{ type: 'text', text: `Could not reach ${ENDPOINT}: ${reason}` }] };
+        throw new Error(`Could not reach ${ENDPOINT}: ${reason}`);
     }
     const body = await response.text();
-    if (!response.ok) {
-        return {
-            isError: true,
-            content: [{ type: 'text', text: `Hubris answered ${response.status}: ${body.slice(0, 600)}` }],
-        };
-    }
+    if (!response.ok)
+        throw new Error(`Hubris answered ${response.status}: ${body.slice(0, 600)}`);
     // Streamable HTTP answers either with plain JSON or with a single SSE frame.
     const payload = body.trimStart().startsWith('{')
         ? body
@@ -84,18 +63,52 @@ async function callRemote(name, args) {
         parsed = JSON.parse(payload);
     }
     catch {
-        return { isError: true, content: [{ type: 'text', text: `Unreadable answer from Hubris: ${body.slice(0, 600)}` }] };
+        throw new Error(`Unreadable answer from Hubris: ${body.slice(0, 600)}`);
+    }
+    if (parsed.error)
+        throw new Error(parsed.error.message ?? 'Hubris returned an error.');
+    if (parsed.result === undefined)
+        throw new Error('Hubris returned no result.');
+    return parsed.result;
+}
+/** The live tool list with a key; the bundled one without a key or when the server is unreachable. */
+async function listTools() {
+    const apiKey = process.env.HUBRIS_API_KEY;
+    if (!apiKey)
+        return TOOLS;
+    try {
+        const { tools } = await rpc(apiKey, 'tools/list', {});
+        return tools && tools.length > 0 ? tools : TOOLS;
+    }
+    catch {
+        return TOOLS;
     }
-    if (parsed.error) {
-        return { isError: true, content: [{ type: 'text', text: parsed.error.message ?? 'Hubris returned an error.' }] };
+}
+/** Forwards one tools/call to the hosted server and returns its result. */
+async function callRemote(name, args) {
+    const apiKey = process.env.HUBRIS_API_KEY;
+    if (!apiKey) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: 'HUBRIS_API_KEY is not set. Create a key at https://hubris.pw/keys and pass it ' +
+                        'to this server through the environment. Listing tools works without one; ' +
+                        'calling them does not.',
+                },
+            ],
+        };
     }
-    if (!parsed.result) {
-        return { isError: true, content: [{ type: 'text', text: 'Hubris returned no result.' }] };
+    try {
+        return await rpc(apiKey, 'tools/call', { name, arguments: args ?? {} });
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }] };
     }
-    return parsed.result;
 }
 const server = new Server({ name: 'hubris', version: PACKAGE_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await listTools() }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => callRemote(request.params.name, request.params.arguments));
 async function main() {
     await server.connect(new StdioServerTransport());