@valbuild/server 0.122.0 → 0.123.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # @valbuild/server
 
+## 0.123.0
+
+### Minor Changes
+
+- [#613](https://github.com/valbuild/val/pull/613) [`c5e7dfd`](https://github.com/valbuild/val/commit/c5e7dfd12aa1371195be642e1c2fb72b6f3e3ce2) Thanks [@freekh](https://github.com/freekh)! - Val's MCP endpoint moves to its own package, and can now upload images
+
+  Everything that serves Val's content tools over MCP — the tool registry, the
+  write path behind it, the request guards and the access-token verification —
+  now lives in **`@valbuild/mcp`** instead of being split between
+  `@valbuild/server` and `@valbuild/next`.
+
+  **Nothing changes for an app that already mounts it.** `initValMcp` is still
+  exported from `@valbuild/next/server` and behaves exactly as before; it is now a
+  ten-line binding over `@valbuild/mcp`, supplying the Next version that
+  `initHandlerOptions` asks for. A host that is not Next can call
+  `initValMcp` from `@valbuild/mcp` directly.
+
+  If you built your own host on `createValTools`, import it from `@valbuild/mcp`
+  rather than `@valbuild/server`; the tool types moved with it.
+
+  ## Image uploads
+
+  An agent can now add an image, with a new `upload_image` tool. It takes a path
+  to a file on the machine your app runs on, or the image inline as base64, and
+  puts it in an `s.image()` field or an `s.images()` gallery.
+
+  Uploads are converted **only where the Studio would convert them**: `encode` is
+  off unless the schema asks for it (`s.image({ encode: { type: "webp" } })`), and
+  when it does, which images are converted, how far they are scaled and when the
+  original wins are the same decisions the browser makes — the same code, now
+  shared. An upload to a schema without `encode` is stored exactly as it arrived,
+  whatever its size.
+
+  One thing the tool does that the Studio does not: it refuses an image the
+  schema's `accept` does not cover, checked on the bytes that would actually be
+  stored. The Studio does not need to — its file picker carries `accept` — and
+  validation reports a mismatch as server-repairable, so nothing downstream would
+  stop it. An agent has no picker. Note the ordering:
+  `s.image({ accept: "image/webp", encode: { type: "webp" } })` still takes a PNG,
+  because the conversion happens first and it is the result that is checked.
+
+  It is the one tool you construct yourself, because it needs an image library
+  and `sharp` ships a compiled binary per platform. Val does not put one in every
+  project that installs it, so you decide:
+
+  ```sh
+  npm install sharp
+  ```
+
+  ```ts
+  import sharp from "sharp";
+  import { createValImageTools } from "@valbuild/mcp";
+  import { sharpImageProcessor } from "@valbuild/mcp/sharp";
+
+  const { valMcpAuthorize, valMcpTools } = initValMcp(valModules, config, {
+    extraTools: createValImageTools(sharpImageProcessor(sharp)),
+  });
+  ```
+
+  Leave `extraTools` out and everything else works as before — the agent can read,
+  validate and edit content, it just cannot add an image. `sharp` is passed in
+  rather than imported, so you can supply another encoder: `ValImageProcessor` is
+  two functions, `read` and `encode`.
+
+  Remotely stored images work too — `s.image().remote()` and
+  `s.images({ remote: true })` — and they need nothing extra from the MCP client.
+  Adding one does not upload anything to Val's content host: the bytes go into the
+  patch store like any other unpublished change, and the push to
+  `remote.val.build` happens when you publish, exactly as it does for an image
+  added through the Studio. All the tool has to do first is ask the project which
+  bucket to name in the ref, and the credential for that is the one your app
+  already has — its API key when it has one, and in local development the
+  `val login` token in your project, the same one `val validate --fix` uses. If
+  you have not logged in, it says so and writes nothing.
+
+  ## `npm create @valbuild` asks
+
+  The starter template now ships the MCP endpoint, and `npm create @valbuild`
+  asks whether you want it — and, if you do, whether agents should be able to
+  upload images, saying that this adds `sharp`. Both default to yes, and both can
+  be answered up front for a scripted setup:
+
+  ```sh
+  pnpm create @valbuild my-app --mcp --no-image-uploads
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`c5e7dfd`](https://github.com/valbuild/val/commit/c5e7dfd12aa1371195be642e1c2fb72b6f3e3ce2), [`53f670c`](https://github.com/valbuild/val/commit/53f670c0cf2d7a03a6d068c78b7874ce77652c2a)]:
+  - @valbuild/shared@0.123.0
+  - @valbuild/ui@0.123.0
+
 ## 0.122.0
 
 ### Minor Changes

package/dist/declarations/src/index.d.ts

@@ -2,10 +2,9 @@ export { createService, Service } from "./Service.js";
 export { defineExternal, ok, err, isExternalResult, EXTERNAL_RESULT, } from "./externalRecords.js";
 export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder, ExternalCtx, ExternalDefinition, ExternalFile, ExternalIssue, ExternalKeyPage, ExternalRecords, ExternalResult, ExternalSearchHit, ExternalSearchPage, ExternalSort, ItemOfModule, ReadonlyRecordHasNoWrites, Returns, } from "./externalRecords.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
-export { createValTools } from "./tools/index.js";
-export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
-export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, ValToolsOptions, } from "./tools/index.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
+export { resolveRemoteFileAuth } from "./valServerConfig.js";
+export type { RemoteFileAuth, ResolveRemoteFileAuthResult, } from "./valServerConfig.js";
 export { ValModuleLoader } from "./ValModuleLoader.js";
 export { getCompilerOptions } from "./getCompilerOptions.js";
 export { ValSourceFileHandler } from "./ValSourceFileHandler.js";
@@ -47,6 +46,9 @@ export { formatPatchSourceError } from "./ValOps.js";
 export { compareWithCapturedReport, readCapturedReport, replaySnapshot, } from "./debug/replaySnapshot.js";
 export type { ReplayComparison, ReplayResult } from "./debug/replaySnapshot.js";
 export type { OrderedPatches, PatchAnalysis, PatchSourceError, PreparedCommit, } from "./ValOps.js";
+export type { ValOps } from "./ValOps.js";
+export type { AuthorId, BinaryFileType, MetadataOfType, Schemas, Sources, } from "./ValOps.js";
+export type { ValServerConfig } from "./ValServer.js";
 /**
  * The local-dev patch store, exported so the CLI's debug tooling can read a
  * snapshot back with the same code the server uses rather than a second

package/dist/declarations/src/valServerConfig.d.ts

@@ -81,4 +81,41 @@ type CredentialBearingUrl = "valBuildUrl" | "valContentUrl";
  * internal http host today.
  */
 export declare function insecureUrlWarning(name: CredentialBearingUrl, url: string): string | null;
+/**
+ * Which credential talks to the content host about REMOTE FILES.
+ *
+ * A separate question from the one `createValOps` answers, and it has to be:
+ * `ValOps` is authenticated per caller, but remote files are project-level —
+ * looking up a project's public id and its buckets, and later pushing bytes to
+ * them, is the same operation whoever asked for it.
+ *
+ * The rule, in order:
+ *
+ * 1. The app's API key, if there is one. Proxy mode always has one; fs mode has
+ *    one when `VAL_API_KEY` is set.
+ * 2. In fs mode, the developer's own `val login` token, read off disk. This is
+ *    the same file `val validate --fix` reads, and it is why local remote
+ *    uploads work with no configuration beyond having logged in.
+ * 3. Nothing, which is an error rather than a fallback.
+ *
+ * Lives here rather than inside `createValServer` because the MCP image tool
+ * needs the same answer, and this is the file that exists so that two callers
+ * cannot disagree about how a project is configured. A registry that decided it
+ * had no credential while the Studio in the same process had one would be a
+ * genuinely confusing afternoon.
+ */
+export type RemoteFileAuth = {
+    apiKey: string;
+} | {
+    pat: string;
+};
+export type ResolveRemoteFileAuthResult = {
+    status: "success";
+    auth: RemoteFileAuth;
+} | {
+    status: "error";
+    errorCode: "project-not-configured" | "pat-error";
+    message: string;
+};
+export declare function resolveRemoteFileAuth(options: ValServerConfig): Promise<ResolveRemoteFileAuthResult>;
 export {};