feat: export workspace files as MCP resources

README.md

@@ -185,7 +185,7 @@ devspace doctor
 - [Setup Guide](https://github.com/Waishnav/devspace/blob/main/docs/setup.md)
 - [ChatGPT Coding Workflow](https://github.com/Waishnav/devspace/blob/main/docs/chatgpt-coding-workflow.md)
 - [Configuration Reference](https://github.com/Waishnav/devspace/blob/main/docs/configuration.md)
-- [Native File Download](https://github.com/Waishnav/devspace/blob/main/docs/artifact-exchange.md)
+- [Native File Exchange](https://github.com/Waishnav/devspace/blob/main/docs/artifact-exchange.md)
 - [Security Model](https://github.com/Waishnav/devspace/blob/main/docs/security.md)
 - [Troubleshooting Gotchas](https://github.com/Waishnav/devspace/blob/main/docs/gotchas.md)
 

docs/artifact-exchange.md

@@ -1,10 +1,46 @@
-# Download a native file
+# Exchange native files
 
-DevSpace can save a file attached or generated by an MCP host, such as ChatGPT,
-directly into an open workspace. Enable the tool with
-`artifacts.enabled` in `~/.devspace/config.jsonc`.
+Enable artifact tools with `artifacts.enabled` in `~/.devspace/config.jsonc`.
+DevSpace supports both directions: attaching an existing workspace file back to
+the MCP host, and downloading a native host file into a workspace.
+
+## Attach a workspace file to the host
+
+Use `export_artifact` when the user wants the original file as an attachment,
+rather than only asking DevSpace to inspect its contents.
+
+```text
+open_workspace
+  -> export_artifact({ workspaceId, path })
+  -> MCP resource link
+  -> host reads the resource and materializes the attachment
+```
+
+```text
+export_artifact({
+  workspaceId: "ws_123",
+  path: "dist/report.pdf"
+})
+```
+
+The source path must resolve to a regular file inside the selected workspace.
+Symlinks whose target escapes the workspace are rejected. DevSpace opens and
+pins the selected file while the export is active, so a later path replacement
+does not change which bytes the host receives.
+
+Exports are short-lived MCP resources under `artifact://devspace/...`. The
+resource expires after five minutes. Text resources are returned through
+`resources/read` as text; binary resources use the MCP `blob` field. The
+materialization limit is the lower of `artifacts.maxFileBytes` and 8 MiB, which
+bounds the base64 expansion required for binary MCP resource responses. No
+public artifact HTTP endpoint or persistent artifact store is created.
 
-## Workflow
+The export direction works on every platform supported by DevSpace.
+
+## Download a host file into a workspace
+
+DevSpace can save a file attached or generated by an MCP host, such as ChatGPT,
+directly into an open workspace.
 
 ```text
 open_workspace
@@ -29,16 +65,14 @@ DevSpace creates missing parent directories and refuses to overwrite an existing
 file. After the download, normal tools can inspect, move, rename, replace, or
 delete it.
 
-## Safety and limits
-
 The `file` input must be the native value supplied by the MCP host. DevSpace does
 not accept pasted download URLs or local source paths. It validates the complete
 file-object shape, trusted OpenAI download hosts, and redirects before streaming.
 Malformed references, unknown fields, absolute paths, traversal, and symlinked
 parents are rejected.
 
 Downloads are streamed under `artifacts.maxFileBytes` and published as
-owner-only files without overwriting an existing destination. The tool is
-currently available on Linux. It is not registered on macOS, Windows, or BSD
-because Node.js does not expose the required descriptor-relative filesystem
-operations there.
+owner-only files without overwriting an existing destination. The download
+direction is currently available only on Linux. It is not registered on macOS,
+Windows, or BSD because Node.js does not expose the required descriptor-relative
+filesystem operations there.

docs/configuration.md

@@ -135,12 +135,15 @@ are `CODEX_COMMAND`, `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`,
 `COPILOT_COMMAND`, `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. DevSpace does not
 persist provider credentials.
 
-## Native artifact download
-
-Set `artifacts.enabled` to `true` when a host needs to save a native attached or
-generated file into an open workspace. `artifacts.maxFileBytes` limits one
-streamed file. The secure publication path is currently available only on
-Linux; the tool is not registered on macOS, Windows, or BSD.
+## Native artifact exchange
+
+Set `artifacts.enabled` to `true` to exchange native files with the MCP host.
+`export_artifact` can attach an existing workspace file through a short-lived
+MCP resource on every supported platform; its effective size limit is the lower
+of `artifacts.maxFileBytes` and 8 MiB. `download_artifact` saves a host-provided
+native file into a workspace, with `artifacts.maxFileBytes` limiting one streamed
+download. The secure download publication path is currently available only on
+Linux; `download_artifact` is not registered on macOS, Windows, or BSD.
 
 ## Environment boundary
 

docs/security.md

@@ -92,13 +92,22 @@ Managed worktrees reduce accidental edits to your active checkout, but they are
 not a security boundary. They are a workflow boundary for isolated coding
 sessions.
 
-## Native File Download
-
-Native file download is an opt-in, one-shot transfer into an already-open
-workspace. `download_artifact` accepts the MCP host's native file value, the
-`workspaceId` returned by `open_workspace`, and an unused relative destination
-path. It returns only the workspace-relative path and does not create a
-persistent artifact service or reusable artifact ID.
+## Native File Exchange
+
+Artifact exchange is opt-in. `export_artifact` exposes one existing workspace
+file as a short-lived MCP resource so the host can materialize it as an
+attachment. The source is canonicalized before export; symlinks whose real
+target escapes the selected workspace are rejected. The selected file handle is
+pinned for the five-minute resource lifetime. Export size is capped by the lower
+of `artifacts.maxFileBytes` and 8 MiB. Binary `resources/read` responses use the
+MCP `blob` field, so the limit also bounds base64 expansion in the MCP response.
+No public download endpoint or persistent artifact store is created for exports.
+
+Native file download is a one-shot transfer into an already-open workspace.
+`download_artifact` accepts the MCP host's native file value, the `workspaceId`
+returned by `open_workspace`, and an unused relative destination path. It
+returns only the workspace-relative path and does not create a persistent
+artifact service or reusable artifact ID.
 
 DevSpace accepts only the documented native-file object and trusted OpenAI
 download hosts and redirects. Arbitrary URL strings, local source paths,
@@ -116,9 +125,12 @@ disabled unless `logging.shellCommands` is `true`.
 
 Do not enable shell command logging if commands may contain secrets.
 
-Artifact tool logs contain bounded workspace ID, validated hostname,
+Download artifact logs contain bounded workspace ID, validated hostname,
 workspace-relative output path, byte count, hash, duration, and status metadata.
+Export logs contain only the tool name, workspace ID, byte count, duration, and
+status metadata; they do not include the source path or resource token.
 `download_artifact` does not log the opaque file value. Raw content, connector
 references, native file IDs, bearer credentials, presigned URLs, host paths,
-temporary paths, and base64 chunks are never included in tool logs or tool
-results.
+temporary paths, and base64 chunks are never included in tool logs. Exported
+file bytes are absent from the `export_artifact` tool result itself; the host
+retrieves them only in the follow-up MCP `resources/read` response.

src/artifact-export.test.ts

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  ARTIFACT_RESOURCE_MAX_BYTES,
+  clearExportedArtifactsForTests,
+  exportWorkspaceArtifact,
+  readExportedArtifactResource,
+  registerArtifactExportTool,
+} from "./artifact-export.js";
+import type { ServerConfig } from "./config.js";
+import type { WorkspaceRegistry } from "./workspaces.js";
+
+async function fixture(t: { after(callback: () => void | Promise<void>): void }) {
+  const root = await mkdtemp(join(tmpdir(), "devspace-artifact-export-"));
+  const workspace = join(root, "workspace");
+  const outside = join(root, "outside");
+  await Promise.all([mkdir(workspace), mkdir(outside)]);
+  t.after(async () => {
+    await clearExportedArtifactsForTests();
+    await rm(root, { recursive: true, force: true });
+  });
+  return { workspace, outside };
+}
+
+function workspaceRegistry(root: string): WorkspaceRegistry {
+  return {
+    getWorkspace(id: string) {
+      assert.equal(id, "ws_test");
+      return { id, root };
+    },
+    resolvePath(_workspace: unknown, path: string) {
+      return resolve(root, path);
+    },
+  } as unknown as WorkspaceRegistry;
+}
+
+async function connectedServer(root: string) {
+  const server = new McpServer({ name: "artifact-export-test", version: "1.0.0" });
+  registerArtifactExportTool(server, {
+    config: {
+      artifactMaxFileBytes: ARTIFACT_RESOURCE_MAX_BYTES,
+      logging: { toolCalls: false },
+    } as unknown as ServerConfig,
+    workspaces: workspaceRegistry(root),
+  });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: "artifact-export-test-client", version: "1.0.0" });
+  await Promise.all([
+    client.connect(clientTransport),
+    server.connect(serverTransport),
+  ]);
+  return {
+    client,
+    close: async () => {
+      await client.close();
+      await server.close();
+    },
+  };
+}
+
+test("export_artifact materializes through resources/read across MCP sessions", async (t) => {
+  const { workspace } = await fixture(t);
+  const bytes = Buffer.from("artifact-diagnostic-marker\n", "utf8");
+  await writeFile(join(workspace, "note.txt"), bytes);
+
+  const first = await connectedServer(workspace);
+  const exported = await first.client.callTool({
+    name: "export_artifact",
+    arguments: { workspaceId: "ws_test", path: "note.txt" },
+  });
+  await first.close();
+
+  const content = exported.content as Array<{
+    type: string;
+    uri?: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+  }>;
+  const link = content.find((item) => item.type === "resource_link");
+  assert.ok(link?.uri);
+  assert.equal(link.name, "note.txt");
+  assert.equal(link.mimeType, "text/plain; charset=utf-8");
+  assert.equal(link.size, bytes.length);
+  assert.match(link.uri, /^artifact:\/\/devspace\/[A-Za-z0-9_-]{43}$/);
+  assert.equal(JSON.stringify(exported).includes(bytes.toString("base64")), false);
+
+  const second = await connectedServer(workspace);
+  const read = await second.client.readResource({ uri: link.uri });
+  await second.close();
+  assert.deepEqual(read.contents, [{
+    uri: link.uri,
+    mimeType: "text/plain; charset=utf-8",
+    text: bytes.toString("utf8"),
+  }]);
+});
+
+test("binary resources use MCP blob content", async (t) => {
+  const { workspace } = await fixture(t);
+  const bytes = Buffer.from([0, 1, 2, 255, 10]);
+  const filePath = join(workspace, "payload.bin");
+  await writeFile(filePath, bytes);
+
+  const exported = await exportWorkspaceArtifact({ workspaceRoot: workspace, filePath });
+  const token = exported.uri.split("/").at(-1) ?? "";
+  const read = await readExportedArtifactResource(token, exported.uri);
+  assert.deepEqual(read.contents, [{
+    uri: exported.uri,
+    mimeType: "application/octet-stream",
+    blob: bytes.toString("base64"),
+  }]);
+});
+
+test("the exact 8 MiB resource boundary remains exportable", async (t) => {
+  const { workspace } = await fixture(t);
+  const filePath = join(workspace, "boundary.bin");
+  await writeFile(filePath, Buffer.alloc(ARTIFACT_RESOURCE_MAX_BYTES, 0x5a));
+
+  const exported = await exportWorkspaceArtifact({ workspaceRoot: workspace, filePath });
+  assert.equal(exported.size, ARTIFACT_RESOURCE_MAX_BYTES);
+});
+
+test("files larger than the MCP resource limit are rejected", async (t) => {
+  const { workspace } = await fixture(t);
+  const filePath = join(workspace, "too-large.bin");
+  await writeFile(filePath, Buffer.alloc(ARTIFACT_RESOURCE_MAX_BYTES + 1, 0x5a));
+
+  await assert.rejects(
+    exportWorkspaceArtifact({ workspaceRoot: workspace, filePath }),
+    /configured MCP resource materialization limit/,
+  );
+});
+
+test("a lower configured per-file limit is enforced", async (t) => {
+  const { workspace } = await fixture(t);
+  const filePath = join(workspace, "configured-limit.bin");
+  await writeFile(filePath, Buffer.alloc(5));
+
+  await assert.rejects(
+    exportWorkspaceArtifact({
+      workspaceRoot: workspace,
+      filePath,
+      maxFileBytes: 4,
+    }),
+    /configured MCP resource materialization limit/,
+  );
+});
+
+test("missing sources fail without exposing their absolute path", async (t) => {
+  const { workspace } = await fixture(t);
+  const filePath = join(workspace, "does-not-exist.txt");
+
+  await assert.rejects(
+    exportWorkspaceArtifact({ workspaceRoot: workspace, filePath }),
+    (error: unknown) => {
+      assert.ok(error instanceof Error);
+      assert.match(error.message, /existing regular file inside the selected workspace/);
+      assert.equal(error.message.includes(workspace), false);
+      return true;
+    },
+  );
+});
+
+test("symlinks resolving outside the workspace are rejected", async (t) => {
+  if (process.platform === "win32") t.skip("symlink fixture differs on Windows");
+  const { workspace, outside } = await fixture(t);
+  const outsideFile = join(outside, "secret.txt");
+  const linkedFile = join(workspace, "linked.txt");
+  await writeFile(outsideFile, "secret");
+  await symlink(outsideFile, linkedFile);
+
+  await assert.rejects(
+    exportWorkspaceArtifact({ workspaceRoot: workspace, filePath: linkedFile }),
+    /must resolve to a file inside the selected workspace/,
+  );
+});
+
+test("expired resources cannot be read", async (t) => {
+  const { workspace } = await fixture(t);
+  const filePath = join(workspace, "short-lived.txt");
+  await writeFile(filePath, "short-lived");
+  const exported = await exportWorkspaceArtifact({
+    workspaceRoot: workspace,
+    filePath,
+    ttlMs: 5,
+  });
+  const token = exported.uri.split("/").at(-1) ?? "";
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, 15));
+
+  await assert.rejects(
+    readExportedArtifactResource(token, exported.uri),
+    /no longer available/,
+  );
+});