Artifact Storage

A local-first artifact storage and versioning system for AI-generated content. Store, manage, and view web apps, PDFs, images, markdown, and more — all through a beautiful web interface or programmatic API.

Features

• 📦 Multiple artifact types: HTML sites, PDFs, images, markdown, code
• 🔢 Automatic versioning: Every upload creates a new version (v1, v2, v3...)
• 🌐 Web viewer: Browse, preview, and manage artifacts with a beautiful UI
• ⭐ Favorites: Pin important artifacts to the top of your collection
• 🤖 MCP integration: AI agents can store artifacts via Model Context Protocol
• 📂 Filesystem storage: Everything stored as plain files in ~/.artifacts/
• 🎨 Modern design: GitHub-style markdown rendering, dark/light themes

Installation

npm install -g artifact-storage
# or
pnpm add -g artifact-storage

Quick Start

# Start the server
artifact-storage server

# Or with options
artifact-storage server --port 3456 --storage ~/.artifacts

Open http://localhost:3456 in your browser.

CLI Usage

# Start HTTP server (default port 3456)
artifact-storage server

# Start MCP server for AI agent integration
artifact-storage mcp

# Show help
artifact-storage --help

MCP Server Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "artifact-storage": {
      "command": "npx",
      "args": ["artifact-storage", "mcp"],
      "env": {
        "ARTIFACT_STORAGE_API": "http://localhost:3456"
      }
    }
  }
}

MCP Tools

• upload_artifact — Upload files/folders as artifacts
• list_artifacts — List all stored artifacts
• get_artifact — Get artifact details
• delete_artifact — Remove an artifact
• view_artifact — Get web viewer URL

Artifact Types

| Type | Description | Viewer | |------|-------------|--------| | html | Static websites (folder with index.html) | Served via proxy with iframe | | pdf | PDF documents | Browser PDF viewer | | image | Images (SVG, PNG, JPG, etc) | Centered image viewer | | markdown | Markdown documents | GitHub-flavored renderer |

REST API

List Artifacts

curl http://localhost:3456/api/artifacts

Create Artifact

curl -X POST http://localhost:3456/api/artifacts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Website",
    "type": "html",
    "version": "v1",
    "files": [
      {"name": "index.html", "content": "<h1>Hello</h1>"},
      {"name": "styles.css", "content": "body { color: red; }"}
    ]
  }'

Favorites API

# Add to favorites
curl -X POST http://localhost:3456/api/favorites/my-artifact

# Remove from favorites
curl -X DELETE http://localhost:3456/api/favorites/my-artifact

# List favorites
curl http://localhost:3456/api/favorites

Web Viewer

Routes

| Route | Description | |-------|-------------| | / | Artifact grid with favorites | | /view/:id/:version | Auto-detect type and view | | /view/:id/:version/html | HTML site viewer (iframe) | | /view/:id/:version/markdown | Markdown viewer (GitHub light theme) | | /view/:id/:version/image | Image viewer | | /view/:id/:version/pdf | PDF viewer | | /raw/:id/versions/:version/:file | Raw file access |

Storage Layout

Artifacts are stored as plain files at ~/.artifacts/:

~/.artifacts/
  my-website/
    metadata.json          # { name, type, createdAt }
    versions.json          # version index
    versions/
      v1/
        index.html
        styles.css
        app.js
      v2/
        index.html
        styles.css
  demo-pdf/
    metadata.json
    versions/
      v1/
        document.pdf

Favorites are stored in ~/.artifacts/favorites.json.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3456 | HTTP server port | | HOST | localhost | Server host | | ARTIFACTS_PATH | ~/.artifacts | Storage directory | | ARTIFACT_STORAGE_API | http://localhost:3456 | MCP server API URL |

Development

# Clone
git clone https://github.com/richardanaya/artifact-storage.git
cd artifact-storage

# Install dependencies
pnpm install

# Build
pnpm build

# Start dev server
pnpm dev

# Type check
pnpm typecheck

# Format code
pnpm format

Architecture

Interface-first architecture with clear separation:

┌─────────────────────────────────────┐
│  HTTP API (index.ts)                │
│  ├── REST endpoints (JSON)            │
│  └── Web viewer (HTML/HTMX)         │
├─────────────────────────────────────┤
│  MCP Server (mcp-server.ts)         │
│  └── AI agent integration            │
├─────────────────────────────────────┤
│  Domain Layer                        │
│  ├── types.ts — Core types         │
│  └── interfaces.ts — Contracts       │
├─────────────────────────────────────┤
│  Storage Layer                       │
│  ├── artifact-store.ts — FS impl   │
│  └── fs-utils.ts — File utilities  │
└─────────────────────────────────────┘

License

MIT © Richard Anaya