@devbux/subq-snap-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devbux
+
+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.

package/README.md

@@ -1,3 +1,346 @@
-# Temporary Holding Version
+# subq-snap-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A standard [Model Context Protocol](https://modelcontextprotocol.io) (MCP)
+server that exposes **SubQ's Snap decision model** as typed tools —
+publishable to npm and runnable anywhere with `npx` or `bunx`.
+
+```bash
+npx -y @devbux/subq-snap-mcp
+```
+
+## What is Snap?
+
+Snap is SubQ's **decision model** (currently `subq-snap-1.1`, public
+preview). It never generates prose. Instead, you give it:
+
+- a **`state`** — a situation described as text or structured JSON,
+- up to **4 images** to evaluate alongside the state, and
+- a set of **typed questions** about that state,
+
+and Snap returns **typed answers with probabilities**:
+
+| Question type | You define | Snap returns |
+| --- | --- | --- |
+| `choice` | 2–255 labelled options (each with an optional description) | the chosen option, a confidence value, and a probability for every option |
+| `score` | an ordered scale of 2–10 level descriptions | a probability-weighted score (it can fall between levels), the level legend, confidence, and per-level probabilities |
+| `noul` | a proposition (optionally with true/false descriptions) | a probability (0..1) that the proposition is true |
+
+Because the output is structured and probabilistic rather than free text,
+Snap is well suited to routing, triage, moderation, risk scoring,
+prioritisation, and any other "decide, don't chat" step inside an agent
+workflow. One call can ask up to 128 questions, and every question sees
+the same state and every image.
+
+Scope: this server wraps SubQ's **Decisions API** and **Models API**. The
+separate `subq-preview` chat model (Chat Completions / Responses APIs,
+structured outputs, function calling) is not a decision model and is out
+of scope here.
+
+## Requirements
+
+- Node.js **>= 18** (or Bun) to run the server.
+- A SubQ API key (see [Getting an API key](#getting-an-api-key)).
+
+## Install & run
+
+The server speaks MCP over **stdio**, so you normally don't run it by hand —
+your MCP client launches it. The commands below are how clients (or you, for a
+quick smoke test) start it.
+
+### npx (Node)
+
+```bash
+SUBQ_API_KEY=your-key npx -y @devbux/subq-snap-mcp
+```
+
+### bunx (Bun)
+
+```bash
+SUBQ_API_KEY=your-key bunx @devbux/subq-snap-mcp
+```
+
+### Global install (npm)
+
+```bash
+npm install -g @devbux/subq-snap-mcp
+SUBQ_API_KEY=your-key subq-snap-mcp
+```
+
+### Global install (Bun)
+
+```bash
+bun add -g @devbux/subq-snap-mcp
+SUBQ_API_KEY=your-key subq-snap-mcp
+```
+
+> The server starts even when `SUBQ_API_KEY` is not set, so clients can
+> still list its tools; each tool call then returns a clear error naming the
+> missing variable instead of crashing.
+
+## Getting an API key
+
+Create an API key in your SubQ account (see [docs.subq.ai](https://docs.subq.ai)),
+then expose it to the server as the `SUBQ_API_KEY` environment variable.
+Never commit your key to source control.
+
+## MCP client configuration
+
+### Generic (`mcpServers` JSON)
+
+Most MCP clients (Claude Desktop, and many others) accept a configuration
+like this — see also [`examples/mcp-config.json`](examples/mcp-config.json):
+
+```json
+{
+  "mcpServers": {
+    "subq": {
+      "command": "npx",
+      "args": ["-y", "@devbux/subq-snap-mcp"],
+      "env": {
+        "SUBQ_API_KEY": "YOUR_SUBQ_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Using Bun instead:
+
+```json
+{
+  "mcpServers": {
+    "subq": {
+      "command": "bunx",
+      "args": ["@devbux/subq-snap-mcp"],
+      "env": {
+        "SUBQ_API_KEY": "YOUR_SUBQ_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add subq \
+  -e SUBQ_API_KEY=YOUR_SUBQ_API_KEY \
+  -- npx -y @devbux/subq-snap-mcp
+```
+
+### Cursor / VS Code
+
+Cursor and VS Code use the same `mcpServers` JSON shape above (Cursor:
+`.cursor/mcp.json` or Settings → MCP; VS Code: `.vscode/mcp.json` uses a
+top-level `"servers"` key with the same per-server fields). Paste the generic
+config and replace the placeholder key.
+
+## Configuration
+
+| Environment variable | Default | Description |
+| --- | --- | --- |
+| `SUBQ_API_KEY` | _(unset)_ | Bearer API key for the SubQ API. Required for tool calls; the server still starts without it. |
+| `SUBQ_BASE_URL` | `https://api.subq.ai` | Base URL of the SubQ API. |
+| `SUBQ_SNAP_MODEL` | `subq-snap-1.1` | Snap model id to request. Can be overridden per call with the tools' optional `model` argument. Use `snap_list_models` to see what your key can access. |
+
+## Tools
+
+All tools return the SubQ API response as JSON text content. Errors (missing
+API key, HTTP 400/401/402/403/422/429/5xx, network failures, timeouts) are
+returned as MCP tool errors (`isError`) with a clear message that includes
+the HTTP status and the API's own error detail — never your API key.
+
+| Tool | Inputs | Output |
+| --- | --- | --- |
+| `snap_decide` | `state` (string \| JSON object \| JSON array), `questions` (map of name → typed question, 1–128), optional `images`, `model` | All answers in one call: `{ model, answers, usage }` |
+| `snap_choice` | `state`, `instructions`, `options` (object: label → description or `null`, 2–255), optional `images`, `model` | One Choice answer under the name `answer` |
+| `snap_score` | `state`, `instructions`, `levels` (array of level descriptions, 2–10, ordered low → high), optional `images`, `model` | One Score answer under the name `answer` |
+| `snap_noul` | `state`, `instructions`, optional `criteria` (`{ "true": ..., "false": ... }` descriptions), optional `images`, `model` | One Noul answer (probability 0..1) under the name `answer` |
+| `snap_list_models` | _(none)_ | `{ object: "list", data: [{ id, name, object, created, owned_by }] }` |
+
+### Question shapes for `snap_decide`
+
+```jsonc
+{
+  "type": "choice",
+  "instructions": "Which team should own this chat?",
+  "criteria": { "nurse_line": "Needs a nurse today", "front_desk": null }
+}
+```
+
+```jsonc
+{
+  "type": "score",
+  "instructions": "How soon should someone respond?",
+  "criteria": ["Within a week", "Within a day", "Within an hour"]
+}
+```
+
+```jsonc
+{
+  "type": "noul",
+  "instructions": "Should a nurse see this chat first?"
+  // "criteria" is optional for noul and omitted when not provided
+}
+```
+
+`instructions` and `criteria` accept structured JSON (objects/arrays) as
+well as strings, so a criterion can carry the data it is judged against.
+
+## Images
+
+Any decision tool accepts an optional `images` array. Each image is an
+object with a `mediaType` (`image/png`, `image/jpeg`, or `image/webp`) and
+the file bytes as one line of `base64` (no `data:` prefix — URLs and
+`data:` URLs are rejected by the API). Every question in the request sees
+every image, alongside the state.
+
+```json
+{
+  "state": "The number row stopped working.",
+  "images": [{ "mediaType": "image/jpeg", "base64": "<base64 of the photo>" }],
+  "questions": {
+    "shows_keyboard": {
+      "type": "noul",
+      "instructions": "Does the photo show a keyboard?"
+    }
+  }
+}
+```
+
+Limits from the SubQ docs:
+
+- At most **4 images** per request; each at most **4 MiB** decoded, and
+  **8 MiB** decoded in total. The request body can be up to 13 MiB.
+- The image bytes must match the declared `mediaType`, or the API fails
+  the request with `422`. This server checks the count, the base64 shape,
+  and the decoded sizes before sending, so those mistakes come back as
+  clear local errors.
+- Each image uses roughly 64–256 image tokens (not the base64 text),
+  counted toward the model's **384K-token** context window together with
+  the request text.
+- Video is not supported; sample up to 4 frames and send them as images.
+- Note: SubQ stores decisions together with their images, under SubQ's
+  data-retention policy.
+
+## Worked example
+
+An employee reports a broken keyboard and attaches a photo. In **one**
+`snap_decide` call you can check the photo, classify the device, and grade
+its wear:
+
+**Request** (tool `snap_decide`):
+
+```json
+{
+  "state": "The number row stopped working.",
+  "images": [{ "mediaType": "image/jpeg", "base64": "<base64 of the photo>" }],
+  "questions": {
+    "shows_keyboard": {
+      "type": "noul",
+      "instructions": "Does the photo show a keyboard?",
+      "criteria": {
+        "true": "A keyboard is the main object",
+        "false": "No keyboard is visible"
+      }
+    },
+    "layout": {
+      "type": "choice",
+      "instructions": "Which keyboard layout is in the photo?",
+      "criteria": {
+        "full_size": "Desktop keyboard with a numeric keypad",
+        "tenkeyless": "Desktop keyboard with no numeric keypad",
+        "laptop": "Built into a laptop",
+        "not_a_keyboard": null
+      }
+    },
+    "wear": {
+      "type": "score",
+      "instructions": "How worn does the keyboard look?",
+      "criteria": ["Looks new", "Everyday wear", "Replace it"]
+    }
+  }
+}
+```
+
+**Response** (shape; exact values come from the live model):
+
+```json
+{
+  "model": "subq-snap-1.1",
+  "answers": {
+    "shows_keyboard": { "type": "noul", "noul": 0.98 },
+    "layout": {
+      "type": "choice",
+      "choice": "tenkeyless",
+      "probabilities": { "full_size": 0.04, "tenkeyless": 0.9, "laptop": 0.05, "not_a_keyboard": 0.01 },
+      "confidence": 0.9
+    },
+    "wear": {
+      "type": "score",
+      "score": 1.35,
+      "legend": { "0": "Looks new", "1": "Everyday wear", "2": "Replace it" },
+      "probabilities": { "0": 0.15, "1": 0.55, "2": 0.3 },
+      "confidence": 0.72
+    }
+  },
+  "usage": { "input_tokens": 210, "output_tokens": 0 }
+}
+```
+
+Pricing note: you pay only for input tokens (`output_tokens` is always 0);
+Snap is $0.04 per million input tokens at the time of writing.
+
+## Development
+
+```bash
+git clone https://github.com/devbux/subq-snap-mcp.git
+cd subq-snap-mcp
+
+npm install
+npm run dev        # run the server from source with tsx (stdio)
+npm run typecheck  # tsc --noEmit
+npm test           # vitest (fake fetch — no live network calls)
+npm run build      # bundle to dist/index.js with tsup
+npm start          # run the built server
+```
+
+Project layout:
+
+```text
+src/
+  index.ts       stdio bootstrap
+  server.ts      MCP server + the five snap_* tools (zod-validated)
+  config.ts      environment parsing (SUBQ_*)
+  snap/
+    client.ts    typed SnapClient for POST /v1/systemone and GET /v1/models
+    types.ts     request/response types for the SubQ API
+test/
+  client.test.ts SnapClient + config unit tests
+```
+
+## Publishing
+
+Releases are published to npm by the **Publish to npm** GitHub Action
+(`.github/workflows/publish.yml`):
+
+1. Bump the version in `package.json`, update `CHANGELOG.md`, and push.
+2. Create a **GitHub Release** for the new version tag (or run the workflow
+   manually with `workflow_dispatch`).
+3. The workflow runs typecheck, tests, and build, then publishes with
+   `npm publish --provenance --access public`.
+
+Notes:
+
+- The workflow expects an `NPM_TOKEN` repository secret (an npm automation
+  token for an account/organisation that owns the `@devbux` scope) **in
+  this repository's settings**.
+- Provenance is enabled (`id-token: write` permission + `--provenance`), so
+  each published version is linked to its GitHub Actions build.
+- This is a **scoped** package (`@devbux/subq-snap-mcp`); `publishConfig.access`
+  is set to `public` in `package.json` so releases are publicly installable.
+- `prepublishOnly` also runs typecheck, tests, and build for manual publishes.
+
+## License
+
+[MIT](LICENSE) © 2026 devbux

package/dist/index.js

@@ -0,0 +1,594 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://api.subq.ai";
+var DEFAULT_MODEL = "subq-snap-1.1";
+function loadConfig(env = process.env) {
+  const apiKey = env.SUBQ_API_KEY?.trim();
+  const baseUrlRaw = env.SUBQ_BASE_URL?.trim();
+  const model = env.SUBQ_SNAP_MODEL?.trim();
+  return {
+    ...apiKey ? { apiKey } : {},
+    baseUrl: (baseUrlRaw ? baseUrlRaw : DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    model: model ? model : DEFAULT_MODEL
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/snap/client.ts
+var SnapError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "SnapError";
+    if (status !== void 0) {
+      this.status = status;
+    }
+  }
+};
+var DEFAULT_BASE_URL2 = "https://api.subq.ai";
+var DEFAULT_MODEL2 = "subq-snap-1.1";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_IMAGES = 4;
+var MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+var MAX_TOTAL_IMAGE_BYTES = 8 * 1024 * 1024;
+function isValidBase64(value) {
+  if (value.length === 0 || value.length % 4 !== 0) return false;
+  if (/\s/.test(value)) return false;
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+  const body = padding > 0 ? value.slice(0, -padding) : value;
+  if (body.includes("=")) return false;
+  for (let i = 0; i < body.length; i += 8192) {
+    if (!/^[A-Za-z0-9+/]+$/.test(body.slice(i, i + 8192))) return false;
+  }
+  return true;
+}
+var SnapClient = class {
+  apiKey;
+  baseUrl;
+  model;
+  fetchImpl;
+  timeoutMs;
+  constructor(options = {}) {
+    if (options.apiKey === void 0 && options.baseUrl === void 0 && options.model === void 0 && options.fetchImpl === void 0 && options.timeoutMs === void 0) {
+      const config = loadConfig();
+      options = { ...options, ...config };
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/+$/, "");
+    this.model = options.model ?? DEFAULT_MODEL2;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Ask Snap one or more typed questions about a state.
+   * Calls `POST /v1/systemone`.
+   */
+  async decide(request) {
+    const questions = {};
+    for (const [name, question] of Object.entries(request.questions)) {
+      if (question.type === "noul" && question.criteria === void 0) {
+        const { criteria: _omitted, ...rest } = question;
+        questions[name] = rest;
+      } else {
+        questions[name] = question;
+      }
+    }
+    const images = request.images;
+    if (images !== void 0 && images.length > 0) {
+      validateImages(images);
+    }
+    const body = {
+      model: request.model ?? this.model,
+      state: request.state,
+      questions,
+      ...images !== void 0 && images.length > 0 ? { images } : {}
+    };
+    const data = await this.requestJson("/v1/systemone", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (typeof data !== "object" || data === null || typeof data.answers !== "object" || data.answers === null) {
+      throw new SnapError(
+        "Unexpected response from the SubQ API: missing 'answers' object."
+      );
+    }
+    return data;
+  }
+  /** List the models available to this API key. Calls `GET /v1/models`. */
+  async listModels() {
+    const data = await this.requestJson("/v1/models", {
+      method: "GET"
+    });
+    if (typeof data !== "object" || data === null || !Array.isArray(data.data)) {
+      throw new SnapError(
+        "Unexpected response from the SubQ API: missing 'data' array."
+      );
+    }
+    return data;
+  }
+  requireApiKey() {
+    if (!this.apiKey) {
+      throw new SnapError(
+        "SUBQ_API_KEY is not set. Set the SUBQ_API_KEY environment variable to your SubQ API key and restart the server."
+      );
+    }
+    return this.apiKey;
+  }
+  async requestJson(path, init) {
+    const apiKey = this.requireApiKey();
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method: init.method,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        ...init.body !== void 0 ? { body: init.body } : {},
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new SnapError(
+          `Request to the SubQ API timed out after ${this.timeoutMs} ms.`
+        );
+      }
+      throw new SnapError(
+        `Network error while contacting the SubQ API: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text.length > 0 ? JSON.parse(text) : void 0;
+    } catch {
+      parsed = void 0;
+    }
+    if (!response.ok) {
+      throw new SnapError(
+        httpErrorMessage(response.status, parsed),
+        response.status
+      );
+    }
+    return parsed;
+  }
+};
+function validateImages(images) {
+  if (images.length > MAX_IMAGES) {
+    throw new SnapError(
+      `Too many images: the Decisions API accepts at most ${MAX_IMAGES} per request.`
+    );
+  }
+  let total = 0;
+  images.forEach((image, index) => {
+    if (!isValidBase64(image.base64)) {
+      throw new SnapError(
+        `images/${index}: base64 must be one line of standard base64 with padding and no data: prefix.`
+      );
+    }
+    const bytes = Buffer.byteLength(image.base64, "base64");
+    if (bytes > MAX_IMAGE_BYTES) {
+      throw new SnapError(
+        `images/${index}: image over 4 MiB (decoded size ${bytes} bytes).`
+      );
+    }
+    total += bytes;
+  });
+  if (total > MAX_TOTAL_IMAGE_BYTES) {
+    throw new SnapError(
+      `Images total ${total} bytes decoded, over the 8 MiB limit.`
+    );
+  }
+}
+function httpErrorMessage(status, body) {
+  let detail = "";
+  if (typeof body === "object" && body !== null) {
+    const raw = body.detail;
+    if (typeof raw === "string") {
+      detail = raw;
+    } else if (typeof raw === "object" && raw !== null) {
+      const type = raw.error_type;
+      const message = raw.message;
+      const parts = [
+        typeof type === "string" ? type : "",
+        typeof message === "string" ? message : ""
+      ].filter((part) => part.length > 0);
+      detail = parts.join(": ");
+    }
+  }
+  let hint;
+  switch (status) {
+    case 400:
+      hint = "the request was rejected (over the model's token limit, or the model rejected it)";
+      break;
+    case 401:
+      hint = "authentication failed: check that SUBQ_API_KEY is set to a valid SubQ API key";
+      break;
+    case 402:
+      hint = "insufficient credits on the SubQ account for this API key";
+      break;
+    case 403:
+      hint = "this API key cannot use the requested model";
+      break;
+    case 422:
+      hint = "the request was invalid";
+      break;
+    case 429:
+      hint = "rate limit exceeded: slow down and retry later";
+      break;
+    case 503:
+      hint = "the SubQ service is temporarily unavailable";
+      break;
+    default:
+      hint = status >= 500 ? "the SubQ API had a server error" : "the request failed";
+  }
+  return `SubQ API error (HTTP ${status}): ${hint}` + (detail ? ` \u2014 ${detail}` : "");
+}
+
+// src/server.ts
+var SINGLE_QUESTION_NAME = "answer";
+var stateSchema = z.union([
+  z.string(),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown())
+]);
+var entrySchema = z.union([
+  z.string(),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+  z.null()
+]);
+var instructionsSchema = z.union([
+  z.string().min(1, "instructions must not be empty"),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+  z.null()
+]);
+function isEntryValue(value) {
+  return value === null || typeof value === "string" || typeof value === "object";
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var imagesSchema = z.array(
+  z.object({
+    mediaType: z.enum(["image/png", "image/jpeg", "image/webp"]),
+    base64: z.string().min(1).refine(isValidBase64, {
+      message: "base64 must be one line of standard base64 with no data: prefix"
+    })
+  })
+).max(4, "at most 4 images per request").describe(
+  "Up to 4 images for this request. PNG, JPEG, or WebP, base64-encoded with no data: prefix; at most 4 MiB decoded each, 8 MiB in total. Every question in the request sees every image."
+);
+var modelSchema = z.string().min(1).optional().describe("Optional Snap model id override (default: subq-snap-1.1).");
+var questionSchema = z.object({
+  type: z.enum(["choice", "score", "noul"]),
+  instructions: z.unknown(),
+  criteria: z.unknown().optional()
+}).superRefine((question, ctx) => {
+  const { type, criteria, instructions } = question;
+  if (!isEntryValue(instructions) || typeof instructions === "string" && instructions.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "instructions must be a non-empty string, a structured object or array, or null",
+      path: ["instructions"]
+    });
+    return;
+  }
+  if (type === "choice") {
+    if (!isPlainObject(criteria)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "choice questions require criteria: an object mapping each option label to its description",
+        path: ["criteria"]
+      });
+      return;
+    }
+    const count = Object.keys(criteria).length;
+    if (count < 2 || count > 255) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `choice questions require 2-255 options, got ${count}`,
+        path: ["criteria"]
+      });
+    }
+    for (const [label, value] of Object.entries(criteria)) {
+      if (!isEntryValue(value)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `choice option "${label}" must map to a description: a string, a structured object or array, or null`,
+          path: ["criteria", label]
+        });
+      }
+    }
+  } else if (type === "score") {
+    if (!Array.isArray(criteria) || criteria.length < 2 || criteria.length > 10 || !criteria.every((level) => isEntryValue(level))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "score questions require criteria: an array of 2-10 ordered level descriptions (strings or structured objects/arrays)",
+        path: ["criteria"]
+      });
+    }
+  } else if (type === "noul") {
+    if (criteria !== void 0) {
+      if (!isPlainObject(criteria)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "noul criteria must be an object with true/false descriptions",
+          path: ["criteria"]
+        });
+      } else {
+        for (const [label, value] of Object.entries(criteria)) {
+          if (!isEntryValue(value)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `noul criteria "${label}" must map to a description: a string, a structured object or array, or null`,
+              path: ["criteria", label]
+            });
+          }
+        }
+      }
+    }
+  }
+});
+function toSnapQuestion(question) {
+  switch (question.type) {
+    case "choice":
+      return {
+        type: "choice",
+        instructions: question.instructions,
+        criteria: question.criteria
+      };
+    case "score":
+      return {
+        type: "score",
+        instructions: question.instructions,
+        criteria: question.criteria
+      };
+    case "noul":
+      return question.criteria === void 0 ? { type: "noul", instructions: question.instructions } : {
+        type: "noul",
+        instructions: question.instructions,
+        criteria: question.criteria
+      };
+  }
+}
+function textResult(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+  };
+}
+function errorResult(err) {
+  const message = err instanceof SnapError ? err.message : err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+function createServer(opts) {
+  const client = opts?.config !== void 0 ? new SnapClient({
+    ...opts.config.apiKey !== void 0 ? { apiKey: opts.config.apiKey } : {},
+    baseUrl: opts.config.baseUrl,
+    model: opts.config.model
+  }) : new SnapClient();
+  const server = new McpServer({
+    name: "subq-snap-mcp",
+    version: "0.1.0"
+  });
+  server.registerTool(
+    "snap_decide",
+    {
+      title: "Snap: decide (typed questions over a state)",
+      description: "Ask SubQ's Snap decision model one or more typed questions (choice, score and/or noul) about a state in a single call. Returns typed answers with probabilities. The state may be text or structured JSON, and up to 4 images may accompany it; every question sees the state and every image.",
+      inputSchema: {
+        state: stateSchema.describe(
+          "The situation to decide about: text, a JSON object, or a JSON array."
+        ),
+        questions: z.record(z.string(), questionSchema).superRefine((questions, ctx) => {
+          const names = Object.keys(questions);
+          if (names.length < 1 || names.length > 128) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `a request needs 1-128 questions, got ${names.length}`
+            });
+          }
+          for (const name of names) {
+            if (name.length > 100) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `question name "${name.slice(0, 24)}..." is over 100 characters`,
+                path: [name]
+              });
+            }
+          }
+        }).describe(
+          "Map of question name (up to 100 characters) to typed question; 1-128 questions. Each question has a type (choice | score | noul), instructions, and criteria: choice = object of option label -> description (string, structured object/array, or null; 2-255 options); score = array of 2-10 ordered level descriptions; noul = optional object of true/false descriptions. Instructions may be text or structured JSON."
+        ),
+        images: imagesSchema.optional(),
+        model: modelSchema
+      }
+    },
+    async ({ state, questions, images, model }) => {
+      try {
+        const typed = {};
+        for (const [name, question] of Object.entries(questions)) {
+          typed[name] = toSnapQuestion(question);
+        }
+        const result = await client.decide({
+          state,
+          questions: typed,
+          ...images ? { images } : {},
+          ...model ? { model } : {}
+        });
+        return textResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "snap_choice",
+    {
+      title: "Snap: choice question",
+      description: `Ask SubQ's Snap decision model a single Choice question: pick one of 2-255 labelled options for a state. Returns the chosen option, a confidence value, and a probability for every option, under the question name "answer".`,
+      inputSchema: {
+        state: stateSchema.describe(
+          "The situation to decide about: text, a JSON object, or a JSON array."
+        ),
+        instructions: instructionsSchema.describe(
+          "What Snap should decide: plain-language text, or structured JSON."
+        ),
+        options: z.record(z.string(), entrySchema).refine(
+          (options) => {
+            const count = Object.keys(options).length;
+            return count >= 2 && count <= 255;
+          },
+          { message: "choice questions require 2-255 options" }
+        ).describe(
+          "Object mapping each option label to a description (string, structured object/array, or null; 2-255 options)."
+        ),
+        images: imagesSchema.optional(),
+        model: modelSchema
+      }
+    },
+    async ({ state, instructions, options, images, model }) => {
+      try {
+        const result = await client.decide({
+          state,
+          questions: {
+            [SINGLE_QUESTION_NAME]: {
+              type: "choice",
+              instructions,
+              criteria: options
+            }
+          },
+          ...images ? { images } : {},
+          ...model ? { model } : {}
+        });
+        return textResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "snap_score",
+    {
+      title: "Snap: score question",
+      description: `Ask SubQ's Snap decision model a single Score question: rate a state on an ordered scale of 2-10 levels you define. Returns a probability-weighted score (it can fall between levels), the level legend, per-level probabilities, and a confidence value, under the question name "answer".`,
+      inputSchema: {
+        state: stateSchema.describe(
+          "The situation to rate: text, a JSON object, or a JSON array."
+        ),
+        instructions: instructionsSchema.describe(
+          "What Snap should rate: plain-language text, or structured JSON."
+        ),
+        levels: z.array(entrySchema).min(2, "score questions require at least 2 levels").max(10, "score questions allow at most 10 levels").describe(
+          "Ordered level descriptions, lowest to highest (2-10). Each level may be a string or a structured entry."
+        ),
+        images: imagesSchema.optional(),
+        model: modelSchema
+      }
+    },
+    async ({ state, instructions, levels, images, model }) => {
+      try {
+        const result = await client.decide({
+          state,
+          questions: {
+            [SINGLE_QUESTION_NAME]: {
+              type: "score",
+              instructions,
+              criteria: levels
+            }
+          },
+          ...images ? { images } : {},
+          ...model ? { model } : {}
+        });
+        return textResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "snap_noul",
+    {
+      title: "Snap: noul question (yes/no probability)",
+      description: `Ask SubQ's Snap decision model a single Noul question: is a proposition about a state true? Returns a calibrated probability (0..1) under the question name "answer".`,
+      inputSchema: {
+        state: stateSchema.describe(
+          "The situation to assess: text, a JSON object, or a JSON array."
+        ),
+        instructions: instructionsSchema.describe(
+          "The proposition Snap should assess: plain-language text, or structured JSON."
+        ),
+        criteria: z.record(z.string(), entrySchema).optional().describe(
+          'Optional descriptions keyed by "true" / "false" explaining what each outcome means. Values may be strings, structured objects/arrays, or null.'
+        ),
+        images: imagesSchema.optional(),
+        model: modelSchema
+      }
+    },
+    async ({ state, instructions, criteria, images, model }) => {
+      try {
+        const result = await client.decide({
+          state,
+          questions: {
+            [SINGLE_QUESTION_NAME]: {
+              type: "noul",
+              instructions,
+              ...criteria !== void 0 ? { criteria } : {}
+            }
+          },
+          ...images ? { images } : {},
+          ...model ? { model } : {}
+        });
+        return textResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "snap_list_models",
+    {
+      title: "Snap: list available models",
+      description: "List the model IDs available to the configured SubQ API key (GET /v1/models, OpenAI-compatible shape). Use a returned id with the endpoint that supports that model; the Decisions tools in this server need a decision model such as subq-snap-1.1.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        const result = await client.listModels();
+        return textResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const config = loadConfig();
+  const server = createServer({ config });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("subq-snap-mcp: server running on stdio");
+}
+main().catch((err) => {
+  console.error("subq-snap-mcp: fatal error starting server:", err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,59 @@
 {
+  "author": "devbux",
+  "bin": {
+    "subq-snap-mcp": "dist/index.js"
+  },
+  "bugs": {
+    "url": "https://github.com/devbux/subq-snap-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^3.25.0"
+  },
+  "description": "A Model Context Protocol server for SubQ's Snap decision model, with typed Choice, Score and Noul tools and image inputs.",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/devbux/subq-snap-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "subq",
+    "snap",
+    "ai",
+    "decision-model",
+    "typescript"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
   "name": "@devbux/subq-snap-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devbux/subq-snap-mcp.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "version": "0.1.1"
+}