bios-mcp 0.1.0-dev.1

package/README.md

@@ -0,0 +1,96 @@
+# BIOS MCP server
+
+The MCP server exposes the authenticated BIOS training and model-serving
+control planes to MCP-compatible automation clients.
+
+Set these environment variables in the MCP client configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "bios-mcp"],
+  "env": {
+    "BIOS_API_KEY": "bios-...",
+    "BIOS_BASE_URL": "https://api.usbios.ai",
+    "BIOS_WORKSPACE_ID": "workspace-id",
+    "BIOS_INFERENCE_KEY": "sk-usf-deployment-key"
+  }
+}
+```
+
+`BIOS_*` is the canonical environment prefix; the legacy `BIOS_*` names are
+still read as a fallback, so existing client configs keep working.
+
+`https://api.usbios.ai` is the canonical production hostname. Use
+`https://api-dev.usbios.ai` explicitly during dev.
+
+For interactive JWT authentication, omit `BIOS_API_KEY` and set
+`BIOS_ACCESS_TOKEN`. The server never guesses credential type from a prefix:
+API keys use `X-API-Key`, while access tokens use `Authorization: Bearer`.
+
+`chat_with_inference` reads the deployment key only from
+`BIOS_INFERENCE_KEY`; a model cannot place it in a tool argument or expose it
+in a transcript. Set `BIOS_INFERENCE_BASE_URL=https://api-dev.usbios.ai`
+explicitly for dev. The tool validates function schemas and matching tool
+response messages, propagates MCP cancellation to the HTTP request, makes one
+non-streaming OpenAI-compatible request, and never retries a dispatched
+inference POST automatically. `BIOS_INFERENCE_TIMEOUT_MS` defaults to
+`900000` (15 minutes). Its idempotency header is propagated, but replay/dedup is
+not claimed without an explicit acknowledgement from the endpoint.
+
+## Safe inference workflow
+
+1. `get_inference_gpu_options` returns inference-fit configurations joined to
+   authoritative deployment prices and stock. `unknown` is not treated as
+   available.
+2. `preflight_inference` validates the exact source, model, GPU, queue, price
+   cap, and wallet-hold terms without creating a deployment or mutating funds.
+3. `create_inference` uses the same request contract. Queueing is opt-in, a
+   maximum total hourly price is explicit, and a GPU alternative is never
+   selected without approval. Its inference key is shown only once.
+4. `get_inference_status` reports durable queue expiry (including
+   `status_reason=queue_expired`), provisioning/loading, endpoint readiness,
+   price cap, notification summary, and wallet authorization. An endpoint is
+   live only when the returned status is `running`.
+5. `get_inference_notifications` reports durable lifecycle-email delivery,
+   bounded retries, and operator-visible dead letters.
+6. `update_inference_policy`, `stop_inference`, `resume_inference`,
+   `restart_inference`, and `delete_inference` manage the lifecycle.
+
+Raw Hugging Face tokens are intentionally excluded from MCP tool inputs. Store
+the token in a platform Hugging Face integration and pass `hf_integration_id`.
+
+`create_training_job` and `resume_training_job` accept an optional
+`idempotency_key`. Reuse the same value after a timeout so the API replays the
+original acknowledgement instead of creating another job, wallet hold, queue
+entry, or GPU request. The MCP server generates a fresh key when it is omitted.
+
+Training and deployment share one authoritative GPU-capacity broker. Server
+priority is evaluated first. Within an equal-priority class, the broker rotates
+across users and preserves FIFO order within each user's own requests. This
+anti-starvation policy prevents one user's large backlog from monopolizing GPU
+capacity; consequently, a newer request from another user can run before an
+older request in a busy user's backlog.
+
+For each eligible request, the broker selects the lowest-ranked approved GPU
+choice that is live, has enough cards, and remains within the accepted total
+hourly price cap. Thus an older request's third choice can receive capacity
+before a newer request's first choice. Unknown/stale provider inventory issues
+no grant. Every vendor mutation requires the broker's short-lived fenced grant,
+and atomic reservations prevent training and deployment replicas from booking
+the same cards.
+
+If capacity disappears before the vendor mutation, a queued request releases
+the grant and returns to its original global position. Expired worker leases
+are fenced and recovered with a new grant identity. Ambiguous provider results
+retain the same immutable provisioning request and grant fence until
+reconciliation proves success or definitive failure, so MCP clients should
+retry with the same idempotency key rather than submit a replacement request.
+
+## Verification
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "bios-mcp",
+  "version": "0.1.0-dev.1",
+  "description": "BIOS MCP server — train and deploy AI models from MCP-compatible automation clients",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bios-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http/main.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "express": "^4.21.2",
+    "pg": "^8.16.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.23",
+    "@types/node": "^22.15.0",
+    "@types/pg": "^8.15.4",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "homepage": "https://usbios.ai/docs/mcp"
+}