Artifacts MCP Server

A Model Context Protocol (MCP) server that provides CRUD operations for artifacts in DeepCoding applications.

Features

• list_artifacts: List all artifacts for the current app
• get_artifact: Get a specific artifact by ID
• create_artifact: Create a new artifact
• update_artifact: Update an existing artifact
• delete_artifact: Delete an artifact

Installation

npm install -g @deepcoding/artifacts-mcp

Usage

The MCP server is designed to be used within the DeepCoding Runner environment. It requires the following environment variables:

• APP_STAGE_TOKEN: Authentication token for the app stage
• RUNNER_BASE_URL: Base URL of the Runner API (defaults to http://localhost:3000)

With Claude CLI

Add to your MCP configuration:

{
  "mcpServers": {
    "artifacts": {
      "command": "npx",
      "args": ["-y", "@deepcoding/artifacts-mcp@latest"],
      "env": {
        "APP_STAGE_TOKEN": "your-app-stage-token",
        "RUNNER_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Integration in DeepCoding Runner

The server is automatically configured and injected into Claude instances running in the DeepCoding Runner environment.

API

All operations are scoped to the app associated with the provided APP_STAGE_TOKEN.

list_artifacts

Lists all artifacts for the current app.

Parameters: None

Returns: A formatted list of artifacts with IDs, names, types, and creation dates.

get_artifact

Retrieves a specific artifact by ID.

Parameters:

• id (string): The ID of the artifact to retrieve

Returns: Full artifact details including content.

create_artifact

Creates a new artifact.

Parameters:

• name (string, required): The name of the artifact
• type (string, required): The type of artifact (e.g., 'document', 'code', 'config', 'image')
• description (string, optional): Description of the artifact
• content (string, optional): Content of the artifact. For images, provide a file path (relative to /workspace) or URL

Returns: Confirmation with the created artifact details. For image artifacts, also returns the image data in MCP image format with base64 data and proper MIME type (supports JPEG and PNG).

update_artifact

Updates an existing artifact.

Parameters:

• id (string, required): The ID of the artifact to update
• name (string, optional): New name for the artifact
• type (string, optional): New type for the artifact
• description (string, optional): New description for the artifact
• content (string, optional): New content for the artifact

Returns: Confirmation with the updated artifact details.

delete_artifact

Deletes an artifact.

Parameters:

• id (string, required): The ID of the artifact to delete

Returns: Confirmation of deletion with the artifact name and ID.

Image Handling

When creating artifacts with type: "image", the MCP server provides enhanced functionality:

• Local Files: Provide a file path relative to /workspace (e.g., "images/photo.jpg")
• Remote URLs: Provide a full URL (e.g., "https://example.com/image.png")
• Supported Formats: JPEG (.jpg, .jpeg) and PNG (.png)
• MCP Response: Returns both text confirmation and the actual image as base64 data with proper MIME type

Example usage:

// Local file
create_artifact({
  name: "Project Logo",
  type: "image",
  content: "assets/logo.png",
});

// Remote URL
create_artifact({
  name: "Reference Image",
  type: "image",
  content: "https://example.com/reference.jpg",
});

Security

• All requests are authenticated using the APP_STAGE_TOKEN
• Operations are scoped to the app associated with the token
• Network communication uses HTTPS in production environments

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

License

MIT