@artifactly/mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# Artifactly
 
-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.
+Agent-first artifact sharing for AI-created content.
+
+Production domain: artifactly.io
+
+## MVP direction
+
+Artifactly is built around one core loop: an authenticated agent publishes an artifact, receives a stable share URL, and a human can view the artifact through a hosted page.
+
+See `docs/database.md` for Supabase migration, owner seed, and API key setup.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run lint
+npm run build
+```

package/bin/artifactly-mcp.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const tsxCli = fileURLToPath(import.meta.resolve("tsx/cli"));
+const entrypoint = resolve(packageRoot, "src/mcp/run-artifactly-mcp.ts");
+const child = spawn(process.execPath, [tsxCli, entrypoint, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/bin/artifactly.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const tsxCli = fileURLToPath(import.meta.resolve("tsx/cli"));
+const entrypoint = resolve(packageRoot, "src/cli/run-artifactly.ts");
+const child = spawn(process.execPath, [tsxCli, entrypoint, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@artifactly/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "files": [
+    "bin",
+    "src/cli",
+    "src/mcp",
+    "README.md"
+  ],
+  "bin": {
+    "artifactly": "bin/artifactly.mjs",
+    "artifactly-mcp": "bin/artifactly-mcp.mjs"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "artifactly": "tsx src/cli/run-artifactly.ts",
+    "generate-api-key": "node scripts/generate-api-key.mjs",
+    "supabase:start": "supabase start",
+    "supabase:reset": "supabase db reset",
+    "supabase:status": "supabase status"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@supabase/supabase-js": "^2.117.2",
+    "better-sqlite3": "^13.0.3",
+    "fflate": "^0.8.3",
+    "next": "16.3.8",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsx": "^4.23.15",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.3.8",
+    "supabase": "^2.119.0",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vitest": "^4.1.10"
+  }
+}

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

@@ -0,0 +1,90 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  createArtifactlyCli,
+  getDefaultCredentialPath,
+  readCredentials,
+} from "./artifactly-cli";
+
+describe("artifactly CLI", () => {
+  it("stores verified login credentials without printing the API key", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-cli-"));
+    const credentialPath = join(dir, "credentials.json");
+    const requests: Array<{ path: string; body: unknown }> = [];
+    const output: string[] = [];
+
+    const cli = createArtifactlyCli({
+      credentialPath,
+      apiBaseUrl: "https://artifactly.example",
+      stdout: (line) => output.push(line),
+      prompt: async () => "123456",
+      postJson: async (path, body) => {
+        requests.push({ path, body });
+        if (path === "/api/auth/request-code") {
+          return { ok: true, email: "agent@example.com", expiresAt: "soon" };
+        }
+        return {
+          ok: true,
+          account: { email: "agent@example.com", workspace: "agent" },
+          apiKey: { secret: "art_test_secret", prefix: "art_test" },
+        };
+      },
+    });
+
+    await cli.run(["login", "--email", "agent@example.com"]);
+
+    expect(requests.map((request) => request.path)).toEqual([
+      "/api/auth/request-code",
+      "/api/auth/verify-code",
+    ]);
+    expect(readCredentials(credentialPath)).toEqual({
+      apiBaseUrl: "https://artifactly.example",
+      apiKey: "art_test_secret",
+      email: "agent@example.com",
+      workspace: "agent",
+    });
+    expect(output.join("\n")).not.toContain("art_test_secret");
+    expect(output.join("\n")).toContain("Logged in as agent@example.com");
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("publishes markdown using stored credentials", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-cli-"));
+    const credentialPath = join(dir, "credentials.json");
+    const output: string[] = [];
+    const cli = createArtifactlyCli({
+      credentialPath,
+      apiBaseUrl: "https://artifactly.example",
+      stdout: (line) => output.push(line),
+      postJson: async () => ({
+        id: "artifact_1",
+        url: "https://artifactly.example/share/agent/hello",
+      }),
+    });
+
+    await cli.run(["login", "--api-key", "art_test_secret", "--email", "agent@example.com"]);
+    await cli.run([
+      "publish",
+      "--title",
+      "Hello",
+      "--content",
+      "# Hello",
+      "--visibility",
+      "unlisted",
+    ]);
+
+    expect(output.at(-1)).toContain("https://artifactly.example/share/agent/hello");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("reports the default credential path under the user home", () => {
+    expect(getDefaultCredentialPath("/Users/alice")).toBe(
+      "/Users/alice/.artifactly/credentials.json",
+    );
+  });
+});

package/src/cli/artifactly-cli.ts

@@ -0,0 +1,221 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export type ArtifactlyCredentials = {
+  apiBaseUrl: string;
+  apiKey: string;
+  email?: string;
+  workspace?: string;
+};
+
+export type PostJson = (
+  path: string,
+  body: unknown,
+  options?: { apiKey?: string },
+) => Promise<unknown>;
+
+type ArtifactlyCliOptions = {
+  apiBaseUrl?: string;
+  credentialPath?: string;
+  stdout?: (line: string) => void;
+  stderr?: (line: string) => void;
+  prompt?: (question: string) => Promise<string>;
+  postJson?: PostJson;
+};
+
+function parseFlags(argv: string[]): Record<string, string | true> {
+  const flags: Record<string, string | true> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg?.startsWith("--")) {
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+    } else {
+      flags[key] = next;
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function readStringFlag(
+  flags: Record<string, string | true>,
+  key: string,
+): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function getDefaultCredentialPath(home = homedir()) {
+  return join(home, ".artifactly", "credentials.json");
+}
+
+export function readCredentials(path = getDefaultCredentialPath()): ArtifactlyCredentials | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ArtifactlyCredentials;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCredentials(
+  credentials: ArtifactlyCredentials,
+  path = getDefaultCredentialPath(),
+) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function defaultPrompt(question: string) {
+  const readline = createInterface({ input, output });
+  try {
+    return await readline.question(question);
+  } finally {
+    readline.close();
+  }
+}
+
+export function createDefaultPostJson(apiBaseUrl: string): PostJson {
+  return async (path, body, options) => {
+    const response = await fetch(`${apiBaseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(options?.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
+      },
+      body: JSON.stringify(body),
+    });
+    const payload = (await response.json().catch(() => ({}))) as unknown;
+    if (!response.ok) {
+      const message =
+        typeof payload === "object" &&
+        payload !== null &&
+        "error" in payload &&
+        typeof payload.error === "string"
+          ? payload.error
+          : `Artifactly API request failed with ${response.status}`;
+      throw new Error(message);
+    }
+    return payload;
+  };
+}
+
+function assertObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Artifactly API returned an unexpected response.");
+  }
+  return value as Record<string, unknown>;
+}
+
+export function createArtifactlyCli(options: ArtifactlyCliOptions = {}) {
+  const apiBaseUrl =
+    options.apiBaseUrl ?? process.env.ARTIFACTLY_API_BASE ?? "https://artifactly.io";
+  const credentialPath = options.credentialPath ?? getDefaultCredentialPath();
+  const stdout = options.stdout ?? ((line: string) => console.log(line));
+  const stderr = options.stderr ?? ((line: string) => console.error(line));
+  const prompt = options.prompt ?? defaultPrompt;
+  const postJson = options.postJson ?? createDefaultPostJson(apiBaseUrl);
+
+  async function login(argv: string[]) {
+    const flags = parseFlags(argv);
+    const email = readStringFlag(flags, "email");
+    const apiKey = readStringFlag(flags, "api-key");
+
+    if (apiKey) {
+      writeCredentials({ apiBaseUrl, apiKey, email }, credentialPath);
+      stdout(`Saved Artifactly credentials${email ? ` for ${email}` : ""}.`);
+      return;
+    }
+
+    if (!email) {
+      throw new Error("Usage: artifactly login --email you@example.com");
+    }
+
+    await postJson("/api/auth/request-code", { email });
+    stdout(`Sent Artifactly login code to ${email}.`);
+    const code = (readStringFlag(flags, "code") ?? (await prompt("Code: "))).trim();
+    const response = assertObject(
+      await postJson("/api/auth/verify-code", { email, code }),
+    );
+    const apiKeyResponse = assertObject(response.apiKey);
+    const account = assertObject(response.account);
+    const secret = String(apiKeyResponse.secret ?? "");
+    if (!secret) {
+      throw new Error("Artifactly API did not return an API key.");
+    }
+    const workspace =
+      typeof account.workspace === "string" ? account.workspace : undefined;
+    writeCredentials({ apiBaseUrl, apiKey: secret, email, workspace }, credentialPath);
+    stdout(`Logged in as ${email}${workspace ? ` (${workspace})` : ""}.`);
+  }
+
+  function whoami() {
+    const credentials = readCredentials(credentialPath);
+    if (!credentials) {
+      throw new Error("Not logged in. Run artifactly login --email you@example.com.");
+    }
+    stdout(`API: ${credentials.apiBaseUrl}`);
+    stdout(`Email: ${credentials.email ?? "unknown"}`);
+    stdout(`Workspace: ${credentials.workspace ?? "unknown"}`);
+  }
+
+  async function publish(argv: string[]) {
+    const credentials = readCredentials(credentialPath);
+    if (!credentials) {
+      throw new Error("Not logged in. Run artifactly login --email you@example.com.");
+    }
+    const flags = parseFlags(argv);
+    const title = readStringFlag(flags, "title");
+    const content = readStringFlag(flags, "content");
+    const visibility = readStringFlag(flags, "visibility") ?? "unlisted";
+    const kind = readStringFlag(flags, "kind") ?? "markdown";
+    if (!title || !content) {
+      throw new Error(
+        "Usage: artifactly publish --title 'Title' --content '# Markdown' [--visibility unlisted]",
+      );
+    }
+    const response = assertObject(
+      await postJson(
+        "/api/artifacts",
+        { title, content, visibility, kind },
+        { apiKey: credentials.apiKey },
+      ),
+    );
+    stdout(`Published ${String(response.url ?? response.id ?? "artifact")}`);
+  }
+
+  async function mcp(argv: string[] = []) {
+    const { listArtifactlyMcpTools } = await import("../mcp/artifactly-mcp");
+    if (argv.includes("--list-tools")) {
+      stdout(JSON.stringify({ tools: listArtifactlyMcpTools() }, null, 2));
+      return;
+    }
+    stdout("Artifactly MCP tools are available.");
+    stdout("Use: artifactly mcp --list-tools");
+    stdout("Configure agents to call the Artifactly MCP entrypoint backed by ~/.artifactly/credentials.json.");
+  }
+
+  async function run(argv: string[]) {
+    const [command, ...rest] = argv;
+    try {
+      if (command === "login") return await login(rest);
+      if (command === "whoami") return whoami();
+      if (command === "publish") return await publish(rest);
+      if (command === "mcp") return await mcp(rest);
+      stdout("Usage: artifactly <login|whoami|publish|mcp>");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      stderr(message);
+      throw error;
+    }
+  }
+
+  return { run };
+}

package/src/cli/run-artifactly.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { createArtifactlyCli } from "./artifactly-cli";
+
+createArtifactlyCli().run(process.argv.slice(2)).catch(() => {
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import packageJson from "../../package.json";
+import {
+  createArtifactlyMcpCallResult,
+  getArtifactlyMcpInstallConfig,
+  listArtifactlyMcpServerTools,
+} from "./artifactly-mcp-server";
+
+describe("Artifactly MCP server packaging", () => {
+  it("exposes installable CLI bins for humans and MCP clients", () => {
+    expect(packageJson.bin).toEqual({
+      artifactly: "bin/artifactly.mjs",
+      "artifactly-mcp": "bin/artifactly-mcp.mjs",
+    });
+    expect(packageJson.dependencies).toHaveProperty("@modelcontextprotocol/sdk");
+    expect(packageJson.dependencies).toHaveProperty("tsx");
+  });
+
+  it("documents the npm/npx MCP client configuration", () => {
+    expect(getArtifactlyMcpInstallConfig()).toEqual({
+      packageName: "@artifactly/mcp",
+      command: "npx",
+      args: ["-y", "--package", "@artifactly/mcp", "artifactly-mcp"],
+      credentialPath: "~/.artifactly/credentials.json",
+      exampleConfig: {
+        mcpServers: {
+          artifactly: {
+            command: "npx",
+            args: ["-y", "--package", "@artifactly/mcp", "artifactly-mcp"],
+          },
+        },
+      },
+    });
+  });
+});
+
+describe("Artifactly MCP stdio server helpers", () => {
+  it("maps Artifactly tools to MCP-compatible tool definitions", () => {
+    expect(listArtifactlyMcpServerTools().map((tool) => tool.name)).toEqual([
+      "artifactly_auth_status",
+      "artifactly_request_login_code",
+      "artifactly_verify_login_code",
+      "artifactly_publish_markdown",
+      "artifactly_list_artifacts",
+      "artifactly_get_artifact",
+    ]);
+  });
+
+  it("returns MCP text content without leaking stored API keys", async () => {
+    const result = await createArtifactlyMcpCallResult({
+      name: "artifactly_auth_status",
+      credentialPath: "/tmp/does-not-exist-artifactly-credentials.json",
+    });
+
+    expect(result.content).toHaveLength(1);
+    expect(result.content[0]).toMatchObject({ type: "text" });
+    expect(result.content[0].text).toContain('"authenticated": false');
+    expect(result.content[0].text).not.toContain("art_");
+  });
+});

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

@@ -0,0 +1,141 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { callArtifactlyMcpTool, listArtifactlyMcpTools } from "./artifactly-mcp.js";
+
+export type ArtifactlyMcpInstallConfig = {
+  packageName: string;
+  command: string;
+  args: string[];
+  credentialPath: string;
+  exampleConfig: {
+    mcpServers: {
+      artifactly: {
+        command: string;
+        args: string[];
+      };
+    };
+  };
+};
+
+type McpTextContent = {
+  type: "text";
+  text: string;
+};
+
+export type ArtifactlyMcpCallResult = {
+  content: McpTextContent[];
+  isError?: boolean;
+};
+
+export function getArtifactlyMcpInstallConfig(): ArtifactlyMcpInstallConfig {
+  const args = ["-y", "--package", "@artifactly/mcp", "artifactly-mcp"];
+  return {
+    packageName: "@artifactly/mcp",
+    command: "npx",
+    args,
+    credentialPath: "~/.artifactly/credentials.json",
+    exampleConfig: {
+      mcpServers: {
+        artifactly: {
+          command: "npx",
+          args,
+        },
+      },
+    },
+  };
+}
+
+export function listArtifactlyMcpServerTools() {
+  return listArtifactlyMcpTools();
+}
+
+function resultToText(value: unknown): ArtifactlyMcpCallResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+export async function createArtifactlyMcpCallResult(input: {
+  name: string;
+  arguments?: Record<string, unknown>;
+  credentialPath?: string;
+  apiBaseUrl?: string;
+}): Promise<ArtifactlyMcpCallResult> {
+  try {
+    return resultToText(await callArtifactlyMcpTool(input));
+  } catch (error) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+const authStatusSchema = z.object({});
+const requestLoginCodeSchema = z.object({
+  email: z.string().email(),
+  name: z.string().optional(),
+});
+const verifyLoginCodeSchema = z.object({
+  email: z.string().email(),
+  code: z.string().min(4),
+});
+const publishMarkdownSchema = z.object({
+  title: z.string().min(1),
+  markdown: z.string().min(1),
+  visibility: z.enum(["public", "unlisted", "private", "gated"]).optional(),
+});
+const listArtifactsSchema = z.object({});
+const getArtifactSchema = z.object({
+  artifactId: z.string().min(1),
+});
+
+const toolSchemas = {
+  artifactly_auth_status: authStatusSchema,
+  artifactly_request_login_code: requestLoginCodeSchema,
+  artifactly_verify_login_code: verifyLoginCodeSchema,
+  artifactly_publish_markdown: publishMarkdownSchema,
+  artifactly_list_artifacts: listArtifactsSchema,
+  artifactly_get_artifact: getArtifactSchema,
+} as const;
+
+export function createArtifactlyMcpServer() {
+  const server = new McpServer({
+    name: "artifactly",
+    version: "0.1.1",
+  });
+
+  for (const tool of listArtifactlyMcpTools()) {
+    const schema = toolSchemas[tool.name as keyof typeof toolSchemas] ?? z.object({});
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.name,
+        description: tool.description,
+        inputSchema: schema,
+      },
+      async (args: Record<string, unknown>) =>
+        createArtifactlyMcpCallResult({ name: tool.name, arguments: args }),
+    );
+  }
+
+  return server;
+}
+
+export async function runArtifactlyMcpStdioServer() {
+  const server = createArtifactlyMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

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

@@ -0,0 +1,91 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { writeCredentials } from "../cli/artifactly-cli";
+import { callArtifactlyMcpTool, listArtifactlyMcpTools } from "./artifactly-mcp";
+
+describe("Artifactly MCP tools", () => {
+  it("exposes the initial agent-native tool list", () => {
+    expect(listArtifactlyMcpTools().map((tool) => tool.name)).toEqual([
+      "artifactly_auth_status",
+      "artifactly_request_login_code",
+      "artifactly_verify_login_code",
+      "artifactly_publish_markdown",
+      "artifactly_list_artifacts",
+      "artifactly_get_artifact",
+    ]);
+  });
+
+  it("reports auth status from the shared credential store", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "artifactly-mcp-"));
+    const credentialPath = join(dir, "credentials.json");
+    writeCredentials(
+      {
+        apiBaseUrl: "https://artifactly.example",
+        apiKey: "art_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    await expect(
+      callArtifactlyMcpTool({ name: "artifactly_auth_status", credentialPath }),
+    ).resolves.toEqual({
+      authenticated: true,
+      apiBaseUrl: "https://artifactly.example",
+      email: "agent@example.com",
+      workspace: "agent",
+    });
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("publishes markdown through the Artifactly API without returning secrets", 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_test_secret",
+        email: "agent@example.com",
+        workspace: "agent",
+      },
+      credentialPath,
+    );
+
+    const result = await callArtifactlyMcpTool({
+      name: "artifactly_publish_markdown",
+      credentialPath,
+      arguments: { title: "Hello", markdown: "# Hello" },
+      postJson: async (path, body, options) => {
+        requests.push({ path, body, apiKey: options?.apiKey });
+        return { id: "artifact_1", url: "https://artifactly.example/share/agent/hello" };
+      },
+    });
+
+    expect(result).toEqual({
+      id: "artifact_1",
+      url: "https://artifactly.example/share/agent/hello",
+    });
+    expect(requests).toEqual([
+      {
+        path: "/api/artifacts",
+        apiKey: "art_test_secret",
+        body: {
+          title: "Hello",
+          content: "# Hello",
+          kind: "markdown",
+          visibility: "unlisted",
+        },
+      },
+    ]);
+    expect(JSON.stringify(result)).not.toContain("art_test_secret");
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/mcp/artifactly-mcp.ts

@@ -0,0 +1,189 @@
+import {
+  createDefaultPostJson,
+  getDefaultCredentialPath,
+  readCredentials,
+  writeCredentials,
+  type PostJson,
+} from "../cli/artifactly-cli.js";
+
+export type ArtifactlyMcpTool = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+type CallToolInput = {
+  name: string;
+  arguments?: Record<string, unknown>;
+  credentialPath?: string;
+  apiBaseUrl?: string;
+  postJson?: PostJson;
+};
+
+function stringArg(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined {
+  const value = args?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function requireStringArg(
+  args: Record<string, unknown> | undefined,
+  key: string,
+): string {
+  const value = stringArg(args, key);
+  if (!value) {
+    throw new Error(`Missing required argument: ${key}`);
+  }
+  return value;
+}
+
+function objectResult(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Artifactly API returned an unexpected response.");
+  }
+  return value as Record<string, unknown>;
+}
+
+export function listArtifactlyMcpTools(): ArtifactlyMcpTool[] {
+  return [
+    {
+      name: "artifactly_auth_status",
+      description: "Check whether local Artifactly credentials are configured.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "artifactly_request_login_code",
+      description: "Request a real Artifactly signup/login email code.",
+      inputSchema: {
+        type: "object",
+        properties: { email: { type: "string" }, name: { type: "string" } },
+        required: ["email"],
+      },
+    },
+    {
+      name: "artifactly_verify_login_code",
+      description:
+        "Verify an email code, create or resume the account, and store the returned API key locally.",
+      inputSchema: {
+        type: "object",
+        properties: { email: { type: "string" }, code: { type: "string" } },
+        required: ["email", "code"],
+      },
+    },
+    {
+      name: "artifactly_publish_markdown",
+      description: "Publish markdown through the Artifactly API using stored credentials.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          markdown: { type: "string" },
+          visibility: { type: "string", enum: ["public", "unlisted", "private", "gated"] },
+        },
+        required: ["title", "markdown"],
+      },
+    },
+    {
+      name: "artifactly_list_artifacts",
+      description: "List recent Artifactly artifacts when the list API is available.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "artifactly_get_artifact",
+      description: "Get Artifactly artifact metadata when the lookup API is available.",
+      inputSchema: {
+        type: "object",
+        properties: { artifactId: { type: "string" } },
+        required: ["artifactId"],
+      },
+    },
+  ];
+}
+
+export async function callArtifactlyMcpTool(input: CallToolInput) {
+  const credentialPath = input.credentialPath ?? getDefaultCredentialPath();
+  const credentials = readCredentials(credentialPath);
+  const apiBaseUrl = input.apiBaseUrl ?? credentials?.apiBaseUrl ?? "https://artifactly.io";
+  const postJson = input.postJson ?? createDefaultPostJson(apiBaseUrl);
+
+  if (input.name === "artifactly_auth_status") {
+    return credentials
+      ? {
+          authenticated: true,
+          apiBaseUrl: credentials.apiBaseUrl,
+          email: credentials.email,
+          workspace: credentials.workspace,
+        }
+      : { authenticated: false, apiBaseUrl };
+  }
+
+  if (input.name === "artifactly_request_login_code") {
+    const email = requireStringArg(input.arguments, "email");
+    const name = stringArg(input.arguments, "name");
+    const response = objectResult(
+      await postJson("/api/auth/request-code", { email, ...(name ? { name } : {}) }),
+    );
+    return {
+      ok: Boolean(response.ok),
+      email: String(response.email ?? email),
+      expiresAt: String(response.expiresAt ?? ""),
+    };
+  }
+
+  if (input.name === "artifactly_verify_login_code") {
+    const email = requireStringArg(input.arguments, "email");
+    const code = requireStringArg(input.arguments, "code");
+    const response = objectResult(
+      await postJson("/api/auth/verify-code", { email, code }),
+    );
+    const apiKey = objectResult(response.apiKey);
+    const account = objectResult(response.account);
+    const secret = String(apiKey.secret ?? "");
+    if (!secret) {
+      throw new Error("Artifactly API did not return an API key.");
+    }
+    const workspace =
+      typeof account.workspace === "string" ? account.workspace : undefined;
+    writeCredentials({ apiBaseUrl, apiKey: secret, email, workspace }, credentialPath);
+    return {
+      authenticated: true,
+      email,
+      workspace,
+      apiKeyPrefix: typeof apiKey.prefix === "string" ? apiKey.prefix : undefined,
+    };
+  }
+
+  if (input.name === "artifactly_publish_markdown") {
+    if (!credentials) {
+      throw new Error("Artifactly credentials are not configured. Run artifactly_request_login_code first.");
+    }
+    const title = requireStringArg(input.arguments, "title");
+    const content = requireStringArg(input.arguments, "markdown");
+    const visibility = stringArg(input.arguments, "visibility") ?? "unlisted";
+    return objectResult(
+      await postJson(
+        "/api/artifacts",
+        { title, content, kind: "markdown", visibility },
+        { apiKey: credentials.apiKey },
+      ),
+    );
+  }
+
+  if (input.name === "artifactly_list_artifacts") {
+    return {
+      error:
+        "Artifact list API is not available yet. This MCP tool is reserved for the next API expansion.",
+    };
+  }
+
+  if (input.name === "artifactly_get_artifact") {
+    return {
+      error:
+        "Artifact lookup API is not available yet. This MCP tool is reserved for the next API expansion.",
+    };
+  }
+
+  throw new Error(`Unknown Artifactly MCP tool: ${input.name}`);
+}

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runArtifactlyMcpStdioServer } from "./artifactly-mcp-server";
+
+runArtifactlyMcpStdioServer().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});