@artifactly/mcp 0.1.7 → 0.1.9

package/README.md

@@ -35,6 +35,43 @@ npx -y --package=@artifactly/mcp artifactly-mcp
 
 The package also exposes a human CLI as `artifactly`.
 
+## Agent MCP usage
+
+Typical MCP client config:
+
+```toml
+[mcp_servers.artifactly]
+command = "npx"
+args = ["-y", "@artifactly/mcp"]
+```
+
+Robust explicit-bin form:
+
+```toml
+[mcp_servers.artifactly]
+command = "npx"
+args = ["-y", "--package=@artifactly/mcp", "artifactly-mcp"]
+```
+
+Authentication flow:
+
+1. Run `artifactly_request_login_code` with an email address.
+2. Run `artifactly_verify_login_code` with the emailed code.
+3. Use `artifactly_auth_status` to inspect local credentials, or pass `validate: true` to confirm the saved API key with the Artifactly server.
+4. Run `artifactly_logout` to clear local credentials.
+
+Artifact workflow notes:
+
+- Default visibility is `unlisted` for agent-created artifacts.
+- 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_publish_file` infers MIME type from file extension unless `mimeType` is supplied; explicit `mimeType` wins.
+- Files larger than 10 MB are rejected before upload to avoid large in-memory base64 payloads.
+- Requests time out after 30 seconds.
+
 Manual publish from a logged-in maintainer account:
 
 ```bash

package/package.json

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

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

@@ -6,6 +6,7 @@ import { describe, expect, it } from "vitest";
 
 import {
   createArtifactlyCli,
+  createDefaultPostJson,
   getDefaultCredentialPath,
   readCredentials,
 } from "./artifactly-cli";
@@ -107,4 +108,23 @@ describe("artifactly CLI", () => {
       "/Users/alice/.artifactly/credentials.json",
     );
   });
+
+  it("uses an explicit timeout signal for default POST requests", async () => {
+    const calls: Array<{ url: string; signal?: AbortSignal }> = [];
+    const postJson = createDefaultPostJson("https://artifactly.example", {
+      timeoutMs: 1234,
+      fetcher: async (url, init) => {
+        calls.push({ url: String(url), signal: init?.signal ?? undefined });
+        return new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      },
+    });
+
+    await expect(postJson("/api/test", { ok: true })).resolves.toEqual({ ok: true });
+    expect(calls).toEqual([
+      { url: "https://artifactly.example/api/test", signal: expect.any(AbortSignal) },
+    ]);
+  });
 });

package/src/cli/artifactly-cli.ts

@@ -17,6 +17,13 @@ export type PostJson = (
   options?: { apiKey?: string },
 ) => Promise<unknown>;
 
+type Fetcher = typeof fetch;
+
+type DefaultPostJsonOptions = {
+  timeoutMs?: number;
+  fetcher?: Fetcher;
+};
+
 type ArtifactlyCliOptions = {
   apiBaseUrl?: string;
   credentialPath?: string;
@@ -57,9 +64,32 @@ export function getDefaultCredentialPath(home = homedir()) {
   return join(home, ".artifactly", "credentials.json");
 }
 
+function normalizeCredentials(value: unknown): ArtifactlyCredentials | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.apiBaseUrl !== "string" || !candidate.apiBaseUrl.trim()) {
+    return null;
+  }
+  if (typeof candidate.apiKey !== "string" || !candidate.apiKey.trim()) {
+    return null;
+  }
+  return {
+    apiBaseUrl: candidate.apiBaseUrl.trim(),
+    apiKey: candidate.apiKey.trim(),
+    ...(typeof candidate.email === "string" && candidate.email.trim()
+      ? { email: candidate.email.trim() }
+      : {}),
+    ...(typeof candidate.workspace === "string" && candidate.workspace.trim()
+      ? { workspace: candidate.workspace.trim() }
+      : {}),
+  };
+}
+
 export function readCredentials(path = getDefaultCredentialPath()): ArtifactlyCredentials | null {
   try {
-    return JSON.parse(readFileSync(path, "utf8")) as ArtifactlyCredentials;
+    return normalizeCredentials(JSON.parse(readFileSync(path, "utf8")));
   } catch {
     return null;
   }
@@ -86,15 +116,21 @@ async function defaultPrompt(question: string) {
   }
 }
 
-export function createDefaultPostJson(apiBaseUrl: string): PostJson {
+export function createDefaultPostJson(
+  apiBaseUrl: string,
+  options: DefaultPostJsonOptions = {},
+): PostJson {
+  const fetcher = options.fetcher ?? fetch;
+  const timeoutMs = options.timeoutMs ?? 30_000;
   return async (path, body, options) => {
-    const response = await fetch(`${apiBaseUrl}${path}`, {
+    const response = await fetcher(`${apiBaseUrl}${path}`, {
       method: "POST",
       headers: {
         "content-type": "application/json",
         ...(options?.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
       },
       body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
     });
     const payload = (await response.json().catch(() => ({}))) as unknown;
     if (!response.ok) {

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

@@ -0,0 +1,18 @@
+import { readFileSync } from "node:fs";
+
+import { describe, expect, it } from "vitest";
+
+describe("Artifactly MCP package documentation", () => {
+  it("documents installed-package behavior for agents", () => {
+    const readme = readFileSync("README.md", "utf8");
+
+    expect(readme).toContain("## Agent MCP usage");
+    expect(readme).toContain("artifactly_request_login_code");
+    expect(readme).toContain("artifactly_verify_login_code");
+    expect(readme).toContain("Default visibility is `unlisted`");
+    expect(readme).toContain("public`, `unlisted`, `private`, and `gated`");
+    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");
+  });
+});

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

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import packageJson from "../../package.json";
 import {
+  createArtifactlyMcpServer,
   createArtifactlyMcpCallResult,
   getArtifactlyMcpInstallConfig,
   listArtifactlyMcpServerTools,
@@ -37,6 +38,41 @@ describe("Artifactly MCP server packaging", () => {
 });
 
 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 } } }>;
+    };
+
+    expect(server.server._serverInfo).toEqual({
+      name: "artifactly",
+      version: packageJson.version,
+    });
+    expect(Object.keys(server._registeredTools.artifactly_auth_status.inputSchema.def.shape)).toContain("validate");
+    expect(
+      server._registeredTools.artifactly_update_artifact.inputSchema.safeParse({
+        artifactId: "artifact_1",
+        description: "",
+      }).success,
+    ).toBe(true);
+    expect(
+      server._registeredTools.artifactly_publish_markdown.inputSchema.safeParse({
+        title: "Gated",
+        markdown: "# Secret",
+        visibility: "gated",
+        accessList: ["agent@example.com"],
+      }).success,
+    ).toBe(true);
+    expect(
+      server._registeredTools.artifactly_list_artifacts.inputSchema.safeParse({
+        limit: 10,
+        cursor: "2026-02-01T00:00:00.000Z",
+        visibility: "gated",
+        kind: "html",
+      }).success,
+    ).toBe(true);
+  });
+
   it("maps Artifactly tools to MCP-compatible tool definitions", () => {
     expect(listArtifactlyMcpServerTools().map((tool) => tool.name)).toEqual([
       "artifactly_auth_status",

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

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+import packageJson from "../../package.json";
 import { callArtifactlyMcpTool, listArtifactlyMcpTools } from "./artifactly-mcp.js";
 
 export type ArtifactlyMcpInstallConfig = {
@@ -83,7 +84,9 @@ export async function createArtifactlyMcpCallResult(input: {
   }
 }
 
-const authStatusSchema = z.object({});
+const authStatusSchema = z.object({
+  validate: z.boolean().optional(),
+});
 const requestLoginCodeSchema = z.object({
   email: z.string().email(),
   name: z.string().optional(),
@@ -97,8 +100,14 @@ const publishMarkdownSchema = z.object({
   title: z.string().min(1),
   markdown: z.string().min(1),
   visibility: z.enum(["public", "unlisted", "private", "gated"]).optional(),
+  accessList: z.array(z.string().email()).optional(),
+});
+const listArtifactsSchema = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+  cursor: z.string().optional(),
+  visibility: z.enum(["public", "unlisted", "private", "gated"]).optional(),
+  kind: z.enum(["markdown", "html", "image", "file", "json", "web_app"]).optional(),
 });
-const listArtifactsSchema = z.object({});
 const getArtifactSchema = z.object({
   artifactId: z.string().min(1),
 });
@@ -107,7 +116,7 @@ const updateArtifactSchema = z.object({
   title: z.string().min(1).optional(),
   markdown: z.string().min(1).optional(),
   content: z.string().min(1).optional(),
-  description: 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(),
 });
@@ -137,7 +146,7 @@ const toolSchemas = {
 export function createArtifactlyMcpServer() {
   const server = new McpServer({
     name: "artifactly",
-    version: "0.1.1",
+    version: packageJson.version,
   });
 
   for (const tool of listArtifactlyMcpTools()) {

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

@@ -48,6 +48,21 @@ describe("Artifactly MCP tools", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
+  it("does not report malformed credential files as authenticated", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    writeFileSync(credentialPath, "{}\n");
+
+    await expect(
+      callArtifactlyMcpTool({ name: "artifactly_auth_status", credentialPath }),
+    ).resolves.toEqual({ authenticated: false, apiBaseUrl: "https://artifactly.io" });
+    await expect(
+      callArtifactlyMcpTool({ name: "artifactly_list_artifacts", credentialPath }),
+    ).rejects.toThrow(/artifactly_request_login_code[\s\S]*artifactly_verify_login_code/);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
   it("can validate auth status against the Artifactly API", async () => {
     const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
     const credentialPath = join(dir, "credentials.json");
@@ -159,6 +174,86 @@ describe("Artifactly MCP tools", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
+  it("publishes gated markdown with access emails in one call", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const requests: Array<{ path: string; body: unknown; apiKey?: string }> = [];
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_t...et",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await expect(
+      callArtifactlyMcpTool({
+        name: "artifactly_publish_markdown",
+        credentialPath,
+        arguments: {
+          title: "Gated",
+          markdown: "# Secret",
+          visibility: "gated",
+          accessList: ["One@Example.com", "two@example.com"],
+        },
+        postJson: async (path, body, options) => {
+          requests.push({ path, body, apiKey: options?.apiKey });
+          return {
+            id: "artifact_1",
+            accessList: ["one@example.com", "two@example.com"],
+          };
+        },
+      }),
+    ).resolves.toMatchObject({
+      id: "artifact_1",
+      accessList: ["one@example.com", "two@example.com"],
+    });
+    expect(requests).toEqual([
+      {
+        path: "/api/artifacts",
+        apiKey: "art_t...et",
+        body: {
+          title: "Gated",
+          content: "# Secret",
+          kind: "markdown",
+          visibility: "gated",
+          accessList: ["One@Example.com", "two@example.com"],
+        },
+      },
+    ]);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("preserves markdown body whitespace when publishing inline markdown", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    let publishedBody: unknown;
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_t...et",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await callArtifactlyMcpTool({
+      name: "artifactly_publish_markdown",
+      credentialPath,
+      arguments: { title: "Whitespace", markdown: "  # Hello\n\n" },
+      postJson: async (_path, body) => {
+        publishedBody = body;
+        return { id: "artifact_1", url: "https://artifactly.example/share/agent/hello" };
+      },
+    });
+
+    expect(publishedBody).toMatchObject({ content: "  # Hello\n\n" });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
   it("lists, gets, updates, and deletes artifacts through authenticated API requests", async () => {
     const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
     const credentialPath = join(dir, "credentials.json");
@@ -175,7 +270,7 @@ describe("Artifactly MCP tools", () => {
 
     const requestJson = async (method: string, path: string, body?: unknown, options?: { apiKey?: string }) => {
       requests.push({ method, path, body, apiKey: options?.apiKey });
-      if (method === "GET" && path === "/api/artifacts") {
+      if (method === "GET" && path.startsWith("/api/artifacts?")) {
         return { artifacts: [{ id: "artifact_1", title: "Hello" }] };
       }
       if (method === "GET" && path === "/api/artifacts/artifact_1") {
@@ -188,7 +283,12 @@ describe("Artifactly MCP tools", () => {
     };
 
     await expect(
-      callArtifactlyMcpTool({ name: "artifactly_list_artifacts", credentialPath, requestJson }),
+      callArtifactlyMcpTool({
+        name: "artifactly_list_artifacts",
+        credentialPath,
+        arguments: { limit: 10, visibility: "gated", kind: "html", cursor: "2026-02-01T00:00:00.000Z" },
+        requestJson,
+      }),
     ).resolves.toEqual({ artifacts: [{ id: "artifact_1", title: "Hello" }] });
     await expect(
       callArtifactlyMcpTool({
@@ -221,7 +321,12 @@ describe("Artifactly MCP tools", () => {
     ).resolves.toEqual({ ok: true, artifactId: "artifact_1" });
 
     expect(requests).toEqual([
-      { method: "GET", path: "/api/artifacts", apiKey: "art_t...et", body: undefined },
+      {
+        method: "GET",
+        path: "/api/artifacts?limit=10&cursor=2026-02-01T00%3A00%3A00.000Z&visibility=gated&kind=html",
+        apiKey: "art_t...et",
+        body: undefined,
+      },
       { method: "GET", path: "/api/artifacts/artifact_1", apiKey: "art_t...et", body: undefined },
       {
         method: "PATCH",
@@ -234,6 +339,29 @@ describe("Artifactly MCP tools", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
+  it("rejects conflicting markdown and content update arguments with a specific error", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_t...et",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await expect(
+      callArtifactlyMcpTool({
+        name: "artifactly_update_artifact",
+        credentialPath,
+        arguments: { artifactId: "artifact_1", markdown: "# Markdown", content: "Plain" },
+      }),
+    ).rejects.toThrow(/Use either markdown or content, not both/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
   it("publishes local HTML and PDF files through the artifact API", async () => {
     const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
     const credentialPath = join(dir, "credentials.json");
@@ -295,6 +423,39 @@ describe("Artifactly MCP tools", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
+  it("uses explicit MIME type instead of extension when publishing files", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const markdownPath = join(dir, "report.md");
+    let publishedBody: unknown;
+    writeFileSync(markdownPath, "# Report");
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_t...et",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await callArtifactlyMcpTool({
+      name: "artifactly_publish_file",
+      credentialPath,
+      arguments: { path: markdownPath, mimeType: "application/pdf" },
+      postJson: async (_path, body) => {
+        publishedBody = body;
+        return { id: "artifact_1", url: "https://artifactly.example/share/agent/report" };
+      },
+    });
+
+    expect(publishedBody).toMatchObject({
+      kind: "file",
+      storageUrl: "data:application/pdf;base64,IyBSZXBvcnQ=",
+    });
+    rmSync(dir, { recursive: true, force: true });
+  });
+
   it("returns a friendly error when publishing a missing file", async () => {
     const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
     const credentialPath = join(dir, "credentials.json");
@@ -318,4 +479,30 @@ describe("Artifactly MCP tools", () => {
 
     rmSync(dir, { recursive: true, force: true });
   });
+
+  it("rejects oversized files before reading them into base64 payloads", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    const bigPath = join(dir, "big.pdf");
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_t...et",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+    writeFileSync(bigPath, Buffer.alloc(10_000_001));
+
+    await expect(
+      callArtifactlyMcpTool({
+        name: "artifactly_publish_file",
+        credentialPath,
+        arguments: { path: bigPath },
+      }),
+    ).rejects.toThrow(/File is too large.*10 MB/);
+
+    rmSync(dir, { recursive: true, force: true });
+  });
 });

package/src/mcp/artifactly-mcp.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { basename, extname } from "node:path";
 
 import {
@@ -32,6 +32,9 @@ type RequestJson = (
   options?: { apiKey?: string },
 ) => Promise<unknown>;
 
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_UPLOAD_BYTES = 10_000_000;
+
 function createDefaultRequestJson(apiBaseUrl: string): RequestJson {
   return async (method, path, body, options) => {
     const response = await fetch(`${apiBaseUrl}${path}`, {
@@ -41,6 +44,7 @@ function createDefaultRequestJson(apiBaseUrl: string): RequestJson {
         ...(options?.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
       },
       ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });
     const payload = (await response.json().catch(() => ({}))) as unknown;
     if (!response.ok) {
@@ -84,6 +88,17 @@ function requireStringArg(
   return value;
 }
 
+function requireRawStringArg(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string {
+  const value = args?.[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Missing required argument: ${key}`);
+  }
+  return value;
+}
+
 function stringArrayArg(
   args: Record<string, unknown> | undefined,
   key: string,
@@ -111,6 +126,12 @@ function booleanArg(args: Record<string, unknown> | undefined, key: string): boo
 
 function readFileForPublish(path: string): Buffer {
   try {
+    const stats = statSync(path);
+    if (stats.size > MAX_UPLOAD_BYTES) {
+      throw new Error(
+        `File is too large: ${path}. Maximum supported upload size is 10 MB.`,
+      );
+    }
     return readFileSync(path);
   } catch (error) {
     const code = typeof error === "object" && error && "code" in error ? String(error.code) : "";
@@ -139,20 +160,39 @@ function inferMimeType(path: string): string {
   return "application/octet-stream";
 }
 
-function kindForMime(path: string, mimeType: string) {
-  const extension = extname(path).toLowerCase();
+function kindForMime(_path: string, mimeType: string) {
   const normalized = mimeType.toLowerCase();
-  if (normalized.includes("html") || extension === ".html" || extension === ".htm") return "html";
-  if (normalized.includes("json") || extension === ".json") return "json";
-  if (normalized.includes("markdown") || extension === ".md" || extension === ".markdown") return "markdown";
+  if (normalized.includes("html")) return "html";
+  if (normalized.includes("json")) return "json";
+  if (normalized.includes("markdown")) return "markdown";
   return "file";
 }
 
+function queryString(params: Record<string, string | number | undefined>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      search.set(key, String(value));
+    }
+  }
+  const serialized = search.toString();
+  return serialized ? `?${serialized}` : "";
+}
+
+function numberArg(args: Record<string, unknown> | undefined, key: string): number | undefined {
+  const value = args?.[key];
+  if (typeof value === "number" && Number.isInteger(value)) {
+    return value;
+  }
+  return undefined;
+}
+
 export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
   return [
     {
       name: "artifactly_auth_status",
-      description: "Check whether local Artifactly credentials are configured.",
+      description:
+        "Check local Artifactly credentials. Pass validate: true to confirm the saved API key with the Artifactly server.",
       inputSchema: { type: "object", properties: { validate: { type: "boolean" } } },
     },
     {
@@ -181,21 +221,32 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
     },
     {
       name: "artifactly_publish_markdown",
-      description: "Publish markdown through the Artifactly API using stored credentials.",
+      description:
+        "Publish markdown through the Artifactly API using stored credentials. Defaults to unlisted visibility; visibility can be public, unlisted, private, or gated.",
       inputSchema: {
         type: "object",
         properties: {
           title: { type: "string" },
           markdown: { type: "string" },
           visibility: { type: "string", enum: ["public", "unlisted", "private", "gated"] },
+          accessList: { type: "array", items: { type: "string" } },
         },
         required: ["title", "markdown"],
       },
     },
     {
       name: "artifactly_list_artifacts",
-      description: "List recent Artifactly artifacts when the list API is available.",
-      inputSchema: { type: "object", properties: {} },
+      description:
+        "List recent Artifactly artifacts without large content bodies. Supports limit (1-100), cursor, visibility, and kind filters.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: { type: "number", minimum: 1, maximum: 100 },
+          cursor: { type: "string" },
+          visibility: { type: "string", enum: ["public", "unlisted", "private", "gated"] },
+          kind: { type: "string", enum: ["markdown", "html", "image", "file", "json", "web_app"] },
+        },
+      },
     },
     {
       name: "artifactly_get_artifact",
@@ -208,7 +259,8 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
     },
     {
       name: "artifactly_update_artifact",
-      description: "Update an existing Artifactly artifact, including visibility and gated access emails.",
+      description:
+        "Update an existing Artifactly artifact, including visibility and gated access emails. Use markdown or content, not both; description may be an empty string to clear it.",
       inputSchema: {
         type: "object",
         properties: {
@@ -234,7 +286,8 @@ export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
     },
     {
       name: "artifactly_publish_file",
-      description: "Publish a local PDF, HTML, JSON, Markdown, or other file through the Artifactly API.",
+      description:
+        "Publish a local PDF, HTML, JSON, Markdown, or other file through the Artifactly API. Defaults to unlisted visibility; explicit mimeType takes precedence over file extension. Files larger than 10 MB are rejected before upload.",
       inputSchema: {
         type: "object",
         properties: {
@@ -328,12 +381,19 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
       throw new Error(LOGIN_GUIDANCE);
     }
     const title = requireStringArg(input.arguments, "title");
-    const content = requireStringArg(input.arguments, "markdown");
+    const content = requireRawStringArg(input.arguments, "markdown");
     const visibility = stringArg(input.arguments, "visibility") ?? "unlisted";
+    const accessList = stringArrayArg(input.arguments, "accessList");
     return objectResult(
       await postJson(
         "/api/artifacts",
-        { title, content, kind: "markdown", visibility },
+        {
+          title,
+          content,
+          kind: "markdown",
+          visibility,
+          ...(accessList ? { accessList } : {}),
+        },
         { apiKey: credentials.apiKey },
       ),
     );
@@ -343,7 +403,12 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
     if (!credentials) {
       throw new Error(LOGIN_GUIDANCE);
     }
-    return objectResult(await requestJson("GET", "/api/artifacts", undefined, { apiKey: credentials.apiKey }));
+    const limit = numberArg(input.arguments, "limit");
+    const cursor = stringArg(input.arguments, "cursor");
+    const visibility = stringArg(input.arguments, "visibility");
+    const kind = stringArg(input.arguments, "kind");
+    const query = queryString({ limit, cursor, visibility, kind });
+    return objectResult(await requestJson("GET", `/api/artifacts${query}`, undefined, { apiKey: credentials.apiKey }));
   }
 
   if (input.name === "artifactly_get_artifact") {
@@ -360,8 +425,11 @@ export async function callArtifactlyMcpTool(input: CallToolInput) {
     }
     const artifactId = requireStringArg(input.arguments, "artifactId");
     const title = stringArg(input.arguments, "title");
-    const markdown = stringArg(input.arguments, "markdown");
-    const content = stringArg(input.arguments, "content");
+    const markdown = optionalStringArg(input.arguments, "markdown");
+    const content = optionalStringArg(input.arguments, "content");
+    if (markdown !== undefined && content !== undefined) {
+      throw new Error("Use either markdown or content, not both.");
+    }
     const description = optionalStringArg(input.arguments, "description");
     const visibility = stringArg(input.arguments, "visibility");
     const accessList = stringArrayArg(input.arguments, "accessList");