@artifactly/mcp 0.1.9 → 0.1.10

package/README.md

@@ -66,11 +66,15 @@ Artifact workflow notes:
 - Supported visibility values are `public`, `unlisted`, `private`, and `gated`.
 - `gated` artifacts can be published with an `accessList` of allowed email addresses or updated later with `artifactly_update_artifact`.
 - `artifactly_list_artifacts` supports `limit`, `cursor`, `visibility`, and `kind` filters and omits large artifact content by default.
-- `artifactly_get_artifact` returns full owner-visible artifact details.
-- `artifactly_update_artifact` accepts either `markdown` or `content`, not both; pass `description: ""` to clear a description.
+- `artifactly_get_artifact` returns full content by default, including base64/data URL file payloads. Pass `metadataOnly: true` to omit `content` and `storageUrl` for bounded metadata reads.
+- `artifactly_update_artifact` accepts either `markdown` or `content`, not both, and preserves text whitespace exactly while rejecting whitespace-only content updates.
+- To replace binary/file content, call `artifactly_update_artifact` with `filePath` and optional `mimeType`; the replacement file becomes the viewer source and clears old inline text content.
+- Pass `description: ""` to clear a description.
 - `artifactly_publish_file` infers MIME type from file extension unless `mimeType` is supplied; explicit `mimeType` wins.
+- Image MIME types such as `image/png` publish as `kind: "image"` and can be listed with `kind: "image"`.
 - Files larger than 10 MB are rejected before upload to avoid large in-memory base64 payloads.
 - Requests time out after 30 seconds.
+- This package currently exposes MCP tools only; resources, resource templates, and prompts are intentionally unsupported.
 
 Manual publish from a logged-in maintainer account:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artifactly/mcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "private": false,
   "files": [
     "bin",

package/src/mcp/artifactly-mcp-docs.test.ts

@@ -14,5 +14,9 @@ describe("Artifactly MCP package documentation", () => {
     expect(readme).toContain("`artifactly_list_artifacts` supports `limit`, `cursor`, `visibility`, and `kind`");
     expect(readme).toContain("Files larger than 10 MB are rejected before upload");
     expect(readme).toContain("Requests time out after 30 seconds");
+    expect(readme).toContain("`artifactly_get_artifact` returns full content by default");
+    expect(readme).toContain("`metadataOnly: true`");
+    expect(readme).toContain("This package currently exposes MCP tools only");
+    expect(readme).toContain("resources, resource templates, and prompts are intentionally unsupported");
   });
 });

package/src/mcp/artifactly-mcp-server.test.ts

@@ -41,7 +41,7 @@ describe("Artifactly MCP stdio server helpers", () => {
   it("registers tool schemas and server info from package metadata", () => {
     const server = createArtifactlyMcpServer() as unknown as {
       server: { _serverInfo: { name: string; version: string } };
-      _registeredTools: Record<string, { inputSchema: { def: { shape: Record<string, unknown> }; safeParse(value: unknown): { success: boolean } } }>;
+      _registeredTools: Record<string, { inputSchema: { def: { shape: Record<string, unknown> }; safeParse(value: unknown): { success: boolean } }; annotations?: Record<string, unknown>; description: string }>;
     };
 
     expect(server.server._serverInfo).toEqual({
@@ -71,6 +71,38 @@ describe("Artifactly MCP stdio server helpers", () => {
         kind: "html",
       }).success,
     ).toBe(true);
+    expect(
+      server._registeredTools.artifactly_publish_file.inputSchema.safeParse({
+        path: "/tmp/chart.png",
+        visibility: "gated",
+        accessList: ["agent@example.com"],
+      }).success,
+    ).toBe(true);
+    expect(
+      server._registeredTools.artifactly_update_artifact.inputSchema.safeParse({
+        artifactId: "artifact_1",
+        filePath: "/tmp/replacement.pdf",
+        mimeType: "application/pdf",
+      }).success,
+    ).toBe(true);
+  });
+
+  it("registers MCP tool annotations and accurate content descriptions", () => {
+    const server = createArtifactlyMcpServer() as unknown as {
+      _registeredTools: Record<string, { annotations?: Record<string, unknown>; description: string }>;
+    };
+
+    expect(server._registeredTools.artifactly_list_artifacts.annotations).toMatchObject({
+      readOnlyHint: true,
+    });
+    expect(server._registeredTools.artifactly_get_artifact.annotations).toMatchObject({
+      readOnlyHint: true,
+    });
+    expect(server._registeredTools.artifactly_delete_artifact.annotations).toMatchObject({
+      destructiveHint: true,
+    });
+    expect(server._registeredTools.artifactly_get_artifact.description).toMatch(/full content/i);
+    expect(server._registeredTools.artifactly_get_artifact.description).toMatch(/metadataOnly/i);
   });
 
   it("maps Artifactly tools to MCP-compatible tool definitions", () => {
@@ -97,6 +129,20 @@ describe("Artifactly MCP stdio server helpers", () => {
     expect(result.content).toHaveLength(1);
     expect(result.content[0]).toMatchObject({ type: "text" });
     expect(result.content[0].text).toContain('"authenticated": false');
+    expect(result.structuredContent).toEqual({ authenticated: false, apiBaseUrl: "https://artifactly.io" });
     expect(result.content[0].text).not.toContain("art_");
   });
+
+  it("returns typed MCP error content", async () => {
+    const result = await createArtifactlyMcpCallResult({
+      name: "artifactly_list_artifacts",
+      credentialPath: "/tmp/does-not-exist-artifactly-credentials.json",
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toMatchObject({
+      error: expect.stringContaining("artifactly_request_login_code"),
+      errorType: "Error",
+    });
+  });
 });

package/src/mcp/artifactly-mcp-server.ts

@@ -27,6 +27,7 @@ type McpTextContent = {
 
 export type ArtifactlyMcpCallResult = {
   content: McpTextContent[];
+  structuredContent?: Record<string, unknown>;
   isError?: boolean;
 };
 
@@ -53,7 +54,12 @@ export function listArtifactlyMcpServerTools() {
 }
 
 function resultToText(value: unknown): ArtifactlyMcpCallResult {
+  const structuredContent =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
   return {
+    ...(structuredContent ? { structuredContent } : {}),
     content: [
       {
         type: "text",
@@ -74,6 +80,12 @@ export async function createArtifactlyMcpCallResult(input: {
   } catch (error) {
     return {
       isError: true,
+      structuredContent: {
+        error: error instanceof Error ? error.message : String(error),
+        errorType: error instanceof Error ? error.name : "Error",
+        ...(error instanceof Error && "status" in error ? { status: (error as { status?: unknown }).status } : {}),
+        ...(error instanceof Error && "details" in error ? { details: (error as { details?: unknown }).details } : {}),
+      },
       content: [
         {
           type: "text",
@@ -110,12 +122,15 @@ const listArtifactsSchema = z.object({
 });
 const getArtifactSchema = z.object({
   artifactId: z.string().min(1),
+  metadataOnly: z.boolean().optional(),
 });
 const updateArtifactSchema = z.object({
   artifactId: z.string().min(1),
   title: z.string().min(1).optional(),
   markdown: z.string().min(1).optional(),
   content: z.string().min(1).optional(),
+  filePath: z.string().min(1).optional(),
+  mimeType: z.string().min(1).optional(),
   description: z.string().max(500).optional(),
   visibility: z.enum(["public", "unlisted", "private", "gated"]).optional(),
   accessList: z.array(z.string().email()).optional(),
@@ -128,6 +143,7 @@ const publishFileSchema = z.object({
   title: z.string().min(1).optional(),
   mimeType: z.string().min(1).optional(),
   visibility: z.enum(["public", "unlisted", "private", "gated"]).optional(),
+  accessList: z.array(z.string().email()).optional(),
 });
 
 const toolSchemas = {
@@ -143,6 +159,14 @@ const toolSchemas = {
   artifactly_publish_file: publishFileSchema,
 } as const;
 
+const toolAnnotations: Record<string, Record<string, boolean>> = {
+  artifactly_auth_status: { readOnlyHint: true },
+  artifactly_list_artifacts: { readOnlyHint: true },
+  artifactly_get_artifact: { readOnlyHint: true },
+  artifactly_delete_artifact: { destructiveHint: true },
+  artifactly_logout: { destructiveHint: true },
+};
+
 export function createArtifactlyMcpServer() {
   const server = new McpServer({
     name: "artifactly",
@@ -157,6 +181,7 @@ export function createArtifactlyMcpServer() {
         title: tool.name,
         description: tool.description,
         inputSchema: schema,
+        ...(toolAnnotations[tool.name] ? { annotations: toolAnnotations[tool.name] } : {}),
       },
       async (args: Record<string, unknown>) =>
         createArtifactlyMcpCallResult({ name: tool.name, arguments: args }),

package/src/mcp/artifactly-mcp.test.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -487,7 +487,7 @@ describe("Artifactly MCP tools", () => {
     writeCredentials(
       {
         apiBaseUrl: "https://artifactly.example",
-        apiKey: "art_t...et",
+        apiKey: "art_test_secret",
         email: "agent@example.com",
         workspace: "agent",
       },
@@ -505,4 +505,138 @@ describe("Artifactly MCP tools", () => {
 
     rmSync(dir, { recursive: true, force: true });
   });
+
+  it("rejects directory paths with a friendly file error", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const directoryPath = join(dir, "folder");
+    mkdirSync(directoryPath);
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await expect(
+      callArtifactlyMcpTool({
+        name: "artifactly_publish_file",
+        credentialPath,
+        arguments: { path: directoryPath },
+      }),
+    ).rejects.toThrow(/Path must point to a file/);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("publishes gated image files with access lists and image kind", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const pngPath = join(dir, "chart.png");
+    let publishedBody: unknown;
+    writeFileSync(pngPath, Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await callArtifactlyMcpTool({
+      name: "artifactly_publish_file",
+      credentialPath,
+      arguments: {
+        path: pngPath,
+        mimeType: "image/png",
+        visibility: "gated",
+        accessList: ["One@Example.com"],
+      },
+      postJson: async (_path, body) => {
+        publishedBody = body;
+        return { id: "artifact_1", accessList: ["one@example.com"] };
+      },
+    });
+
+    expect(publishedBody).toMatchObject({
+      kind: "image",
+      storageUrl: "data:image/png;base64,iVBORw==",
+      visibility: "gated",
+      accessList: ["One@Example.com"],
+    });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("preserves update whitespace and rejects whitespace-only updates locally", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const requests: unknown[] = [];
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await callArtifactlyMcpTool({
+      name: "artifactly_update_artifact",
+      credentialPath,
+      arguments: { artifactId: "artifact_1", markdown: "  # Title\n" },
+      requestJson: async (_method, _path, body) => {
+        requests.push(body);
+        return { artifact: { id: "artifact_1" } };
+      },
+    });
+    expect(requests).toEqual([{ markdown: "  # Title\n" }]);
+    await expect(
+      callArtifactlyMcpTool({
+        name: "artifactly_update_artifact",
+        credentialPath,
+        arguments: { artifactId: "artifact_1", content: "   " },
+      }),
+    ).rejects.toThrow(/Content cannot be whitespace-only/);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("replaces artifact files explicitly through update", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const pdfPath = join(dir, "replacement.pdf");
+    let bodySent: unknown;
+    writeFileSync(pdfPath, Buffer.from("%PDF-1.4"));
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await callArtifactlyMcpTool({
+      name: "artifactly_update_artifact",
+      credentialPath,
+      arguments: { artifactId: "artifact_1", filePath: pdfPath, mimeType: "application/pdf" },
+      requestJson: async (_method, _path, body) => {
+        bodySent = body;
+        return { artifact: { id: "artifact_1", kind: "file" } };
+      },
+    });
+
+    expect(bodySent).toMatchObject({
+      kind: "file",
+      storageUrl: "data:application/pdf;base64,JVBERi0xLjQ=",
+    });
+    rmSync(dir, { recursive: true, force: true });
+  });
 });

package/src/mcp/artifactly-mcp.ts

@@ -35,6 +35,18 @@ type RequestJson = (
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_UPLOAD_BYTES = 10_000_000;
 
+export class ArtifactlyApiError extends Error {
+  status: number;
+  details: unknown;
+
+  constructor(message: string, status: number, details: unknown) {
+    super(message);
+    this.name = "ArtifactlyApiError";
+    this.status = status;
+    this.details = details;
+  }
+}
+
 function createDefaultRequestJson(apiBaseUrl: string): RequestJson {
   return async (method, path, body, options) => {
     const response = await fetch(`${apiBaseUrl}${path}`, {
@@ -55,7 +67,7 @@ function createDefaultRequestJson(apiBaseUrl: string): RequestJson {
         typeof payload.error === "string"
           ? payload.error
           : `Artifactly API request failed with ${response.status}`;
-      throw new Error(message);
+      throw new ArtifactlyApiError(message, response.status, payload);
     }
     return payload;
   };
@@ -77,6 +89,14 @@ function optionalStringArg(
   return typeof value === "string" ? value.trim() : undefined;
 }
 
+function optionalRawStringArg(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const value = args?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
 function requireStringArg(
   args: Record<string, unknown> | undefined,
   key: string,
@@ -127,6 +147,9 @@ function booleanArg(args: Record<string, unknown> | undefined, key: string): boo
 function readFileForPublish(path: string): Buffer {
   try {
     const stats = statSync(path);
+    if (!stats.isFile()) {
+      throw new Error(`Path must point to a file: ${path}`);
+    }
     if (stats.size > MAX_UPLOAD_BYTES) {
       throw new Error(
         `File is too large: ${path}. Maximum supported upload size is 10 MB.`,
@@ -157,6 +180,10 @@ function inferMimeType(path: string): string {
   if (extension === ".json") return "application/json";
   if (extension === ".md" || extension === ".markdown") return "text/markdown";
   if (extension === ".txt") return "text/plain";
+  if (extension === ".png") return "image/png";
+  if (extension === ".jpg" || extension === ".jpeg") return "image/jpeg";
+  if (extension === ".gif") return "image/gif";
+  if (extension === ".webp") return "image/webp";
   return "application/octet-stream";
 }
 
@@ -165,6 +192,7 @@ function kindForMime(_path: string, mimeType: string) {
   if (normalized.includes("html")) return "html";
   if (normalized.includes("json")) return "json";
   if (normalized.includes("markdown")) return "markdown";
+  if (normalized.startsWith("image/")) return "image";
   return "file";
 }
 
@@ -250,10 +278,10 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
     },
     {
       name: "artifactly_get_artifact",
-      description: "Get Artifactly artifact metadata when the lookup API is available.",
+      description: "Get an Artifactly artifact. Returns full content by default, including base64/data URL file payloads; pass metadataOnly: true to omit content and storageUrl.",
       inputSchema: {
         type: "object",
-        properties: { artifactId: { type: "string" } },
+        properties: { artifactId: { type: "string" }, metadataOnly: { type: "boolean" } },
         required: ["artifactId"],
       },
     },
@@ -268,6 +296,8 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
           title: { type: "string" },
           markdown: { type: "string" },
           content: { type: "string" },
+          filePath: { type: "string" },
+          mimeType: { type: "string" },
           description: { type: "string" },
           visibility: { type: "string", enum: ["public", "unlisted", "private", "gated"] },
           accessList: { type: "array", items: { type: "string" } },
@@ -295,6 +325,7 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
           title: { type: "string" },
           mimeType: { type: "string" },
           visibility: { type: "string", enum: ["public", "unlisted", "private", "gated"] },
+          accessList: { type: "array", items: { type: "string" } },
         },
         required: ["path"],
       },
@@ -416,7 +447,15 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
       throw new Error(LOGIN_GUIDANCE);
     }
     const artifactId = requireStringArg(input.arguments, "artifactId");
-    return objectResult(await requestJson("GET", `/api/artifacts/${artifactId}`, undefined, { apiKey: credentials.apiKey }));
+    const metadataOnly = booleanArg(input.arguments, "metadataOnly");
+    const result = objectResult(await requestJson("GET", `/api/artifacts/${artifactId}`, undefined, { apiKey: credentials.apiKey }));
+    if (metadataOnly && result.artifact && typeof result.artifact === "object" && !Array.isArray(result.artifact)) {
+      const { content: _content, storageUrl: _storageUrl, ...metadata } = result.artifact as Record<string, unknown>;
+      void _content;
+      void _storageUrl;
+      return { ...result, artifact: metadata };
+    }
+    return result;
   }
 
   if (input.name === "artifactly_update_artifact") {
@@ -425,22 +464,41 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
     }
     const artifactId = requireStringArg(input.arguments, "artifactId");
     const title = stringArg(input.arguments, "title");
-    const markdown = optionalStringArg(input.arguments, "markdown");
-    const content = optionalStringArg(input.arguments, "content");
+    const markdown = optionalRawStringArg(input.arguments, "markdown");
+    const content = optionalRawStringArg(input.arguments, "content");
+    const filePath = stringArg(input.arguments, "filePath");
     if (markdown !== undefined && content !== undefined) {
       throw new Error("Use either markdown or content, not both.");
     }
+    if ((markdown !== undefined || content !== undefined) && filePath) {
+      throw new Error("Use either filePath or text content, not both.");
+    }
+    const textContent = markdown ?? content;
+    if (textContent !== undefined && !textContent.trim()) {
+      throw new Error("Content cannot be whitespace-only.");
+    }
     const description = optionalStringArg(input.arguments, "description");
     const visibility = stringArg(input.arguments, "visibility");
     const accessList = stringArrayArg(input.arguments, "accessList");
+    let replacement: Record<string, unknown> = {};
+    if (filePath) {
+      const mimeType = stringArg(input.arguments, "mimeType") ?? inferMimeType(filePath);
+      const kind = kindForMime(filePath, mimeType);
+      const file = readFileForPublish(filePath);
+      replacement = {
+        kind,
+        storageUrl: `data:${mimeType};base64,${file.toString("base64")}`,
+      };
+    }
     return objectResult(
       await requestJson(
         "PATCH",
         `/api/artifacts/${artifactId}`,
         {
           ...(title ? { title } : {}),
-          ...(markdown ? { markdown } : {}),
-          ...(content ? { content } : {}),
+          ...(markdown !== undefined ? { markdown } : {}),
+          ...(content !== undefined ? { content } : {}),
+          ...replacement,
           ...(description !== undefined ? { description } : {}),
           ...(visibility ? { visibility } : {}),
           ...(accessList ? { accessList } : {}),
@@ -466,21 +524,25 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
     const title = stringArg(input.arguments, "title") ?? titleFromPath(path);
     const mimeType = stringArg(input.arguments, "mimeType") ?? inferMimeType(path);
     const visibility = stringArg(input.arguments, "visibility") ?? "unlisted";
+    const accessList = stringArrayArg(input.arguments, "accessList");
     const kind = kindForMime(path, mimeType);
     const file = readFileForPublish(path);
+    const fileLike = kind === "file" || kind === "image";
     const payload =
-      kind === "file"
+      fileLike
         ? {
             title,
             kind,
             storageUrl: `data:${mimeType};base64,${file.toString("base64")}`,
             visibility,
+            ...(accessList ? { accessList } : {}),
           }
         : {
             title,
             kind,
             content: file.toString("utf8"),
             visibility,
+            ...(accessList ? { accessList } : {}),
           };
     return objectResult(
       await postJson("/api/artifacts", payload, { apiKey: credentials.apiKey }),