Artifactly

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

npm run typecheck
npm test
npm run lint
npm run build

npm publishing

The MCP package is published as @artifactly/mcp.

Codex and other MCP clients can launch the server with either of these forms:

npx -y @artifactly/mcp

npx -y --package=@artifactly/mcp artifactly-mcp

The package also exposes a human CLI as artifactly.

Agent MCP usage

Typical MCP client config:

[mcp_servers.artifactly]
command = "npx"
args = ["-y", "@artifactly/mcp"]

Robust explicit-bin form:

[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 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.
• App-hosting MCP tools wrap the public API-key routes for web_app artifacts:
  • artifactly_create_web_app creates a placeholder web_app artifact for the hosting tools.
  • artifactly_list_app_env, artifactly_set_app_env, and artifactly_delete_app_env manage redacted per-app env/secrets.
  • artifactly_publish_app_bundle accepts source files with inline content, contentBase64, or local filePath values and queues a background build job; Docker work does not run in the MCP call. When server-side worker dispatch is configured, the API triggers the Docker-capable GitHub Actions worker immediately and also keeps the scheduled worker fallback.
  • artifactly_enqueue_app_build queues an image build for already-materialized source, and artifactly_get_app_build_status polls job status.
  • artifactly_deploy_app deploys an already-built image reference and returns runtime readiness details so a started Fly machine is not confused with a DNS/HTTP-reachable app.
  • artifactly_list_custom_domains, artifactly_add_custom_domain, and artifactly_delete_custom_domain manage custom-domain status and DNS instructions without exposing provider credentials.
• 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:

npm publish --access public

Trusted publishing uses .github/workflows/npm-publish.yml. Configure npm trusted publishing for:

• Package: @artifactly/mcp
• Repository: erck0004/ai-project-artifactly
• Workflow: npm-publish.yml
• Environment: npm

After that, publish a new package version by bumping package.json, pushing the change, then publishing a GitHub Release for the matching commit/tag.