Zipline MCP Server

An MCP (Model Context Protocol) server that allows you to upload files to a Zipline-compatible host. This server provides tools for uploading files, validating them, and generating upload commands.

Features

• Upload files to a Zipline instance
• Validate files before uploading
• Preview upload commands
• Get only the download URL after upload
• List and search user files stored on the Zipline server
• Support for multiple file types, including:
  • Text/code: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml
  • Images: png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif

Installation

Global Installation

To install the server globally so you can use it with npx:

npm install -g zipline-mcp

Local Installation

To install the server as a dependency in your project:

npm install zipline-mcp

Usage

Using with npx

If you installed the server globally, you can run it directly:

npx zipline-mcp

Adding to MCP Client Configuration

To use this server with an MCP client (like Claude Desktop), you need to add it to your client's configuration file.

MCP-Zipline Integration Guide

Quickstart Configuration

Add this minimal configuration to your MCP client (e.g., Claude Desktop):

# YAML format
mcpServers:
  zipline:
    command: npx
    args: ['-y', 'zipline-mcp']
    environment:
      ZIPLINE_TOKEN: 'your-api-token-here'
      ZIPLINE_ENDPOINT: 'http://localhost:3000'

// JSON format
{
  "mcpServers": {
    "zipline": {
      "command": "npx",
      "args": ["-y", "zipline-mcp"],
      "environment": {
        "ZIPLINE_TOKEN": "your-api-token-here",
        "ZIPLINE_ENDPOINT": "http://localhost:3000"
      }
    }
  }
}

Detailed Configuration Options

Required Settings

• command: The executable to run (typically "npx")
• args: Array containing ["zipline-mcp"]
• environment.ZIPLINE_TOKEN: Your Zipline API token
• environment.ZIPLINE_ENDPOINT: The URL of your Zipline server (default is "http://localhost:3000")

Optional Settings

• environment.ZIPLINE_FORMAT: File naming format. Supported values: "random", "uuid", "date", "name", "gfycat" (alias for "random-words"), "random-words". Defaults to "random".
• environment.ZIPLINE_ENDPOINT: Custom Zipline server URL
• environment.ZIPLINE_DISABLE_SANDBOXING: Disable per-user sandboxing for the tmp_file_manager tool. Set to "true" to disable sandboxing and use the shared ~/.zipline_tmp directory for all users. Defaults to "false" (sandboxing enabled).
• environment.ALLOWED_EXTENSIONS: Override the list of allowed file extensions for upload and validation. Provide a comma-separated list (e.g., .txt,.md,.pdf,.docx). If set, this will replace the default list of allowed extensions. Useful for restricting or expanding supported file types in your deployment.

Security Best Practices

1. Store API tokens in environment variables, not in config files
2. Use HTTPS for all connections to Zipline servers

Troubleshooting Common Issues

Authentication Failures

• Symptom: "Invalid authorization token" errors
• Solutions:
  • Verify token validity
  • Check for typos in the ZIPLINE_TOKEN value
  • Ensure token is passed via environment variable

Architecture Overview

The Zipline MCP Server acts as a bridge between MCP clients and Zipline's file hosting service. Here's how the components interact:

graph LR
    A[MCP Client] --> B[MCP Server]
    B --> C[Zipline API]
    C --> D[(Zipline Storage)]

Key Components

1. MCP Client: Initiates file upload requests (e.g., Claude Desktop)
2. MCP Server:
   • Validates files locally
   • Generates upload commands
   • Handles authentication with Zipline
3. Zipline API: Processes upload requests and returns URLs
4. Zipline Storage: Persistent file storage system

Typical Workflow

1. Client sends file path to MCP server
2. Server validates file type and size
3. Server constructs authenticated API request
4. Zipline processes upload and returns URL
5. Server formats response for MCP client

Format Options

The format parameter controls how uploaded files are named on the Zipline server. Here are the supported formats:

random

Generates a random filename with characters, with length defined by the server configuration. This is the default format.

uuid

Generates a UUID-based filename (e.g., 550e8400-e29b-41d4-a716-446655440000).

date

Uses the current date/time formatted according to the server's default date format. Note that date formatting is handled entirely by the Zipline server.

name

Uses the original filename without its extension (e.g., document.txt becomes document).

gfycat

Alias for random-words. Provides human-readable "random words" style filenames.

random-words

Generates human-readable filenames using random words (e.g., happy-purple-elephant).

Format Normalization and Validation

• Case-insensitive: All format values are case-insensitive (e.g., UUID, uuid, and Uuid are equivalent).
• Alias handling: gfycat is automatically mapped to random-words.
• Error handling: Invalid format values will result in an "Invalid format" error.
• Default behavior: If the format parameter is omitted, the server uses its configured default format (typically random).

Examples

# Use UUID format
upload_file_to_zipline(filePath: "document.txt", format: "uuid")

# Use human-readable format (via alias)
upload_file_to_zipline(filePath: "document.txt", format: "gfycat")

# Case-insensitive usage
upload_file_to_zipline(filePath: "document.txt", format: "RANDOM-WORDS")

Enhanced Upload Options

The Zipline MCP Server now supports additional optional headers that provide enhanced control over file uploads. These headers are sent as x-zipline-* headers to the Zipline server.

x-zipline-deletes-at

Controls when the uploaded file should be automatically deleted.

Formats:

• Relative duration: Strings like "1d" (1 day), "2h" (2 hours), "30m" (30 minutes)
• Absolute date: ISO-8601 format with "date=" prefix, e.g., "date=2025-12-31T23:59:59Z"

Examples:

// Delete after 24 hours
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '1d',
});

// Delete at specific date
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: 'date=2025-12-31T23:59:59Z',
});

Validation:

• Relative durations must be positive and use valid units (d, h, m)
• Absolute dates must be in ISO-8601 format and specify a future date
• Invalid formats will be rejected with descriptive error messages

x-zipline-password

Protects the uploaded file with a password. When this header is provided, users will need to enter the password to access the file.

Format:

• Non-empty string value

Examples:

uploadFile({
  filePath: 'secret.txt',
  format: 'random',
  password: 'my-secret-password',
});

Validation:

• Password must be a non-empty string
• Whitespace-only passwords are rejected
• Security: Passwords are never logged or exposed in error messages

x-zipline-max-views

Limits the number of times a file can be viewed before it becomes unavailable. Each successful view decrements the counter.

Format:

• Non-negative integer (0 or greater)

Examples:

// Allow 10 views
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 10,
});

// Allow single view (disposable link)
uploadFile({
  filePath: 'document.txt',
  format: 'random',
  maxViews: 1,
});

Validation:

• Must be an integer ≥ 0
• Negative numbers and non-integer values are rejected
• When counter reaches 0, file becomes eligible for removal

x-zipline-folder

Specifies the ID of the folder where the upload should be placed. The folder must exist on the Zipline server.

Format:

• Alphanumeric string (letters and numbers only)

Examples:

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  folder: 'myfolder123',
});

Validation:

• Must be a non-empty alphanumeric string
• Special characters and whitespace are rejected
• If the specified folder doesn't exist, the upload will fail

Combining Multiple Headers

You can combine multiple headers for enhanced control:

uploadFile({
  filePath: 'document.txt',
  format: 'random',
  deletesAt: '7d', // Delete after 7 days
  password: 'secret123', // Password protect
  maxViews: 5, // Allow 5 views
  folder: 'shared', // Place in "shared" folder
});

Error Handling

All headers are validated locally before the upload request is sent to the server. If any header is invalid:

• The upload is aborted immediately
• A descriptive error message is returned
• No HTTP request is made to the Zipline server
• The error message explains exactly what needs to be fixed

Backward Compatibility

All enhanced headers are optional. Existing code that doesn't use these headers will continue to work exactly as before. The new functionality only activates when you explicitly provide these parameters.

Available Tools

This server provides the following tools:

upload_file_to_zipline

Uploads a file to the Zipline server and returns a detailed success message.

• filePath: Path to the file to upload. Supported extensions: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml, png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif
• originalName: (optional) Original filename to preserve during download. This parameter is sent as the x-zipline-original-name header to the Zipline server. The original filename will be used when downloading the file, not when storing it. Must be a non-empty string without path separators.

Example Prompts for Users:

• "Upload the file '/path/to/document.pdf' to Zipline"
• "Upload my file at '/home/user/images/photo.jpg' and preserve the original name"
• "I want to upload '/path/to/data.csv' with the original name 'sales-data.csv'"
• "Upload file '/path/to/script.py' to Zipline"
• "Can you upload '/path/to/report.docx' for me?"

validate_file

Checks if a file exists and is suitable for upload.

• filePath: Path to the file to validate. Supported extensions: txt, md, gpx, html, json, xml, csv, js, css, py, sh, yaml, yml, png, jpg, jpeg, gif, webp, svg, bmp, tiff, ico, heic, avif

Example Prompts for Users:

• "Check if '/path/to/document.pdf' is valid for upload"
• "Validate the file at '/home/user/images/photo.jpg'"
• "Is '/path/to/data.csv' suitable for uploading to Zipline?"
• "Can you validate '/path/to/script.py' for me?"
• "Check if '/path/to/report.docx' can be uploaded"

list_user_files

Lists and searches files that you have previously uploaded to the Zipline server.

• page: (optional) Page number for pagination (default: 1)
• perPage: (optional) Number of items per page (default: 20)
• searchField: (optional) Field to search in (e.g., "name", "originalName", "type")
• searchQuery: (optional) Search query string
• filter: (optional) Filter by file type or other criteria
• sort: (optional) Sort field (e.g., "createdAt", "size", "name")
• order: (optional) Sort order ("asc" or "desc", default: "desc")

Example Prompts for Users:

• "List all my files on Zipline"
• "Show me the first page of my uploaded files"
• "Search for files with 'document' in the name"
• "Find all PDF files that I've uploaded"
• "List my files sorted by creation date, newest first"
• "Show me 10 files per page, page 2"
• "Search for files with 'report' in the original name"
• "List my files sorted by size, largest first"
• "Find all image files I've uploaded"

tmp_file_manager

Minimal, sandboxed file management with per-user isolation. Each user gets their own sandbox directory based on their ZIPLINE_TOKEN. Only bare filenames are allowed (no subdirectories or path traversal). All operations are strictly limited to the user's sandbox.

• command: One of:
  • LIST — List all files in the user's sandbox
  • CREATE <filename> — Create or overwrite a file (optionally provide content)
  • OPEN <filename> or READ <filename> — Read file content (max 1MB)
  • PATH <filename> — Get the absolute path of a file in the sandbox
  • DELETE <filename> — Delete a file from the sandbox
• content: (optional) String content for CREATE

Examples:

• LIST
• CREATE notes.txt (with or without content)
• OPEN notes.txt
• READ notes.txt
• PATH notes.txt
• DELETE notes.txt

Example Prompts for Users:

• "List all files in my sandbox"
• "Create a file named 'notes.txt' with content 'Meeting notes from today'"
• "Read the content of 'config.json'"
• "Get the absolute path of 'data.csv'"
• "Delete the file 'temp.txt'"
• "Show me all files in my temporary directory"
• "Create a new file called 'draft.md' with some content"
• "Open and read the 'settings.json' file"
• "What's the full path to 'output.txt'?"
• "Remove 'old_file.txt' from my sandbox"

Sandboxing Configuration:

• Per-user sandboxing is enabled by default
• To disable sandboxing and use the shared ~/.zipline_tmp directory for all users, set ZIPLINE_DISABLE_SANDBOXING=true in your environment
• When sandboxing is disabled, session locking and TTL cleanup are also disabled

Per-User Sandboxing (when enabled):

• Each user gets a unique sandbox directory at ~/.zipline_tmp/users/{hash} where hash is a SHA-256 hash of the user's ZIPLINE_TOKEN
• Sandboxes are automatically created with 0700 permissions for security
• All file operations are isolated within the user's sandbox
• Sandboxes older than 24 hours are automatically cleaned up

Session Locking (when sandboxing is enabled):

• Each user's sandbox is locked during operations to prevent concurrent access
• Locks automatically expire after 30 minutes
• The system prevents race conditions when multiple clients access the same sandbox

Safety:

• Only bare filenames allowed (no /, \, .., or absolute paths)
• Any attempt to access outside the user's sandbox is refused with an explicit error
• Files larger than 1MB cannot be read
• Subdirectories are not supported
• Each user's sandbox is isolated from others (when sandboxing is enabled)

download_external_url

A new tool has been added: download_external_url. It lets the MCP server (and therefore models) download an external HTTP(S) URL into the caller's sandbox and returns the absolute filesystem path to the saved file.

• Tool name: download_external_url
• Purpose: Download an external HTTP(S) resource into the per-user sandbox and return the absolute path where the file was stored.
• Input schema:
  • url (string) — required — HTTP or HTTPS URL to download
  • timeoutMs (number) — optional — request timeout in milliseconds (default: 30000)
  • maxFileSizeBytes (number) — optional — maximum allowed file size in bytes (default: 100 _ 1024 _ 1024 = 100 MB)
• Behavior:
  • Validates the provided URL and only allows http: and https: schemes.
  • Uses an AbortController to enforce the configured timeout.
  • Checks the Content-Length header when present and rejects downloads that declare a size larger than the configured maximum.
  • Downloads into the user's sandbox directory (same sandbox used by the tmp_file_manager tool) and returns the absolute path, e.g. /home/user/.zipline_tmp/users/<hash>/file.ext.
  • If the remote resource does not provide a filename, a safe deterministic name is used.
  • Partial files are cleaned up on failure to avoid leaving incomplete artifacts in the sandbox.
  • Structured logs are emitted via the existing sandbox logging facility for observability.

Usage example (MCP tool call)

• Example input: { "url": "https://example.com/files/document.pdf", "timeoutMs": 30000, "maxFileSizeBytes": 104857600 }
• Example successful response content: "✅ DOWNLOAD COMPLETE\n\nLocal path: /home/user/.zipline_tmp/users/abc123/document.pdf"

Security & safety considerations

• Only http and https are accepted. Other schemes (ftp, file, etc.) are rejected.
• Default file size limit: 100 MB. You can override via maxFileSizeBytes but be cautious.
• The downloader follows redirects but enforces the maximum redirect behavior in code (to avoid redirect loops).
• All downloads are saved inside the per-user sandbox; filenames are validated and sanitized using the same rules as tmp_file_manager (no path separators, no dot segments, no absolute paths).
• The server logs download activity with sanitized paths (user portion masked) for observability; secrets (such as tokens) are never logged.
• If you require domain allow-listing to restrict where the server can download from, consider adding a hostname whitelist at the MCP server configuration level before enabling this tool for production usage.

Example Prompts for Users:

• "Download the PDF from 'https://example.com/document.pdf' to my sandbox"
• "Download 'https://example.com/data.csv' with a timeout of 60 seconds"
• "Download the image from 'https://example.com/image.jpg' with a max file size of 50MB"
• "Download the file from 'https://example.com/report.pdf' and save it to my sandbox"
• "Can you download 'https://example.com/config.json' for me?"
• "Download 'https://example.com/archive.zip' with a custom timeout of 45 seconds"
• "I need to download 'https://example.com/data.json' with a max size of 10MB"

list_user_files

A new tool has been added: list_user_files. It allows you to list and search files that you have previously uploaded to the Zipline server.

• Tool name: list_user_files
• Purpose: List and search user files stored on the Zipline server with support for pagination, filtering, sorting, and searching.
• Input schema:
  • page (number) — optional — Page number for pagination (default: 1)
  • perPage (number) — optional — Number of items per page (default: 20)
  • searchField (string) — optional — Field to search in (e.g., "name", "originalName", "type")
  • searchQuery (string) — optional — Search query string
  • filter (string) — optional — Filter by file type or other criteria
  • sort (string) — optional — Sort field (e.g., "createdAt", "size", "name")
  • order (string) — optional — Sort order ("asc" or "desc", default: "desc")
• Behavior:
  • Fetches files from the Zipline API with the specified parameters
  • Supports pagination to handle large numbers of files
  • Allows searching within specific fields using searchField and searchQuery
  • Supports filtering and sorting of results
  • Returns a structured response with file information and pagination metadata

Usage example (MCP tool call)

• Example input:

  {
    "page": 1,
    "perPage": 10,
    "searchField": "name",
    "searchQuery": "document",
    "sort": "createdAt",
    "order": "desc"
  }
  

• Example successful response content:

  {
    "files": [
      {
        "id": "file123",
        "name": "random-string",
        "originalName": "document.pdf",
        "size": 1024,
        "type": "application/pdf",
        "url": "https://zipline.example.com/file123",
        "createdAt": "2025-01-15T10:30:45.123Z",
        "expiresAt": null,
        "maxViews": null,
        "views": 5
      }
    ],
    "total": 25,
    "page": 1,
    "pages": 3
  }
  

File Model

The tool returns files with the following structure:

• id: Unique identifier for the file
• name: The filename as stored on the server
• originalName: The original filename when uploaded
• size: File size in bytes
• type: MIME type of the file
• url: Direct URL to access the file
• createdAt: When the file was uploaded (ISO 8601 format)
• expiresAt: When the file will expire (if applicable)
• maxViews: Maximum view limit (if applicable)
• views: Current view count

Search and Filter Options

The tool provides powerful search and filtering capabilities:

• Search: Use searchField and searchQuery to search within specific fields
  • Supported search fields: "name", "originalName", "type"
  • Search is case-insensitive and supports partial matches
• Filter: Use the filter parameter to filter by file type or other criteria
• Sort: Use sort and order to sort results by any field
  • Supported sort fields: "createdAt", "size", "name", "views"
  • Order can be "asc" (ascending) or "desc" (descending)

Notes for integrators

• This tool is exported by the MCP server and can be invoked programmatically by MCP clients or models.
• The implementation lives in src/userFiles.ts and the MCP registration is in src/index.ts.
• Tests were added under src/userFiles.test.ts to exercise pagination, searching, filtering, sorting, and error handling.

get_user_file

A new tool has been added: get_user_file. It allows you to retrieve detailed information about a specific file stored on the Zipline server.

• Tool name: get_user_file
• Purpose: Get detailed information about a specific file stored on the Zipline server
• Input schema:
  • id (string) — required — File ID or filename to retrieve information for
• Behavior:
  • Fetches file information from the Zipline API using the file ID or filename
  • Returns comprehensive file metadata including size, type, views, favorites status, and more
  • Handles URL encoding of special characters in file IDs

Usage example (MCP tool call)

• Example input:

  {
    "id": "file123"
  }
  

• Example successful response content:

  📁 FILE INFORMATION
  
  📁 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5
  🔗 URL: http://localhost:3000/u/file123
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

Example Prompts for Users:

• "Get detailed information about the file with ID 'abc123'"
• "Show me the details for file 'document.pdf'"
• "I need to see the metadata for file 'xyz789'"
• "What are the properties of the file named 'my-image.jpg'?"
• "Get information about the file with ID 'file123'"

update_user_file

A new tool has been added: update_user_file. It allows you to update properties of a specific file stored on the Zipline server.

• Tool name: update_user_file
• Purpose: Update properties of a specific file stored on the Zipline server
• Input schema:
  • id (string) — required — File ID or filename to update
  • favorite (boolean) — optional — Set/unset as favorite
  • maxViews (number) — optional — Maximum allowed views (>= 0)
  • password (string | null) — optional — Set password (string), remove password (null)
  • originalName (string) — optional — Set or update the original filename
  • type (string) — optional — Set or update the file MIME type
  • tags (string[]) — optional — Array of tag IDs to set for this file
  • name (string) — optional — Rename the file
• Behavior:
  • Updates file properties using PATCH request to the Zipline API
  • Only updates fields that are explicitly provided (undefined fields are ignored)
  • Supports setting or removing passwords by passing string or null
  • Returns the updated file information

Usage example (MCP tool call)

• Example input:

  {
    "id": "file123",
    "favorite": true,
    "maxViews": 10,
    "password": "secret123"
  }
  

• Example successful response content:

  ✅ FILE UPDATED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  🔗 URL: http://localhost:3000/u/file123
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

Example Prompts for Users:

• "Set file 'abc123' as a favorite"
• "Update file 'document.pdf' to have a maximum of 10 views"
• "Add password protection to file 'xyz789' with password 'secret123'"
• "Remove the password from file 'file123'"
• "Change the original name of file 'abc123' to 'my-updated-document.pdf'"
• "Rename file 'xyz789' to 'new-name.pdf'"
• "Set the MIME type of file 'file123' to 'application/pdf'"
• "Add tags ['tag1', 'tag2'] to file 'abc123'"
• "Update file 'xyz789' to be a favorite with maxViews of 5 and password 'secure'"

delete_user_file

A new tool has been added: delete_user_file. It allows you to delete a specific file stored on the Zipline server.

• Tool name: delete_user_file
• Purpose: Delete a specific file stored on the Zipline server
• Input schema:
  • id (string) — required — File ID or filename to delete
• Behavior:
  • Deletes the file using DELETE request to the Zipline API
  • Returns the file information that was deleted (for confirmation)
  • Handles URL encoding of special characters in file IDs

Usage example (MCP tool call)

• Example input:

  {
    "id": "file123"
  }
  

• Example successful response content:

  ✅ FILE DELETED SUCCESSFULLY!
  
  ⭐🔒 document.pdf
  🆔 ID: file123
  📅 Created: 1/15/2025
  📊 Size: 1.2 MB
  🏷️ Type: application/pdf
  👁️ Views: 5/10
  🔗 URL: http://localhost:3000/u/file123
  
  📄 Original Name: my-document.pdf
  🏷️ Tags: tag1, tag2
  📁 Folder ID: folder123
  

Example Prompts for Users:

• "Delete file with ID 'abc123'"
• "Remove file 'document.pdf' from the server"
• "Delete the file named 'my-image.jpg'"
• "Permanently delete file 'xyz789'"
• "I want to delete the file with ID 'file123'"

Sandbox Path Resolution

The tmp_file_manager tool uses a secure path resolution mechanism to ensure all file operations stay within sandbox boundaries. This is implemented through the resolveSandboxPath function which provides the following security guarantees:

Path Validation:

• Filename Validation: All filenames are validated to prevent path traversal attacks
• Absolute Path Resolution: Converts relative filenames to absolute paths within the sandbox
• Boundary Enforcement: Ensures resolved paths cannot escape the sandbox directory
• Error Handling: Throws SandboxPathError for any violation with clear error messages

Security Features:

• Input Sanitization: Rejects filenames containing path separators (/, \), dot segments (..), or absolute paths
• Path Normalization: Resolves paths to their canonical form to prevent symbolic link attacks
• Containment Verification: Verifies that the final resolved path is within the sandbox boundaries
• Audit Logging: All sandbox operations are logged with sanitized paths for security monitoring

Implementation Details:

// Example of secure path resolution
function resolveSandboxPath(filename: string): string {
  const userSandbox = getUserSandbox();

  // Validate filename first
  const validationError = validateFilename(filename);
  if (validationError) {
    throw new SandboxPathError(validationError);
  }

  const resolved = path.resolve(userSandbox, filename);

  // Security: Ensure resolved path is within sandbox
  if (!resolved.startsWith(userSandbox)) {
    throw new SandboxPathError(`Path traversal attempt: ${filename}`);
  }

  return resolved;
}

Error Examples:

• CREATE ../evil.txt → Error: Filenames must not include path separators, dot segments, or be empty. Only bare filenames in ~/.zipline_tmp are allowed.
• OPEN /etc/passwd → Error: Filenames must not include path separators, dot segments, or be empty. Only bare filenames in ~/.zipline_tmp are allowed.
• READ ../../system/file → Error: Path traversal attempt: ../../system/file

Logging and Auditing:

All sandbox operations are logged with security-sensitive information sanitized:

[2025-01-15T10:30:45.123Z] SANDBOX_OPERATION: FILE_CREATED - notes.txt - Path: /home/user/.zipline_tmp/users/[HASH] - Size: 42 bytes

User-specific paths are masked with [HASH] to prevent token leakage in logs while maintaining traceability.

Development

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Setup

1. Clone the repository:

git clone https://github.com/dorogoy/zipline-mcp.git
cd zipline-mcp

2. Install dependencies:

npm install

Scripts

• npm run build: Build the TypeScript project.
• npm run start: Run the built server.
• npm run dev: Run the server in development mode with tsx.
• npm run test: Run tests in watch mode.
• npm run test:run: Run tests once.
• npm run lint: Lint the codebase using ESLint.
• npm run lint:fix: Automatically fix lint errors where possible.
• npm run format: Format the codebase with Prettier.
• npm run format:check: Check if the codebase is formatted.

Linting

Running Lint Locally

To check for lint errors:

npm run lint

To automatically fix fixable issues:

npm run lint:fix

Or use the Makefile:

make lint

Lint in CI

• Linting runs automatically on every pull request and before every release.
• The CI will fail if there are any lint errors.
• Linting is required for merging PRs.

Interpreting Lint Results

• Errors will be shown in the terminal or CI logs.
• Fix errors locally using npm run lint:fix or by editing the code as indicated.
• Warnings do not block CI but should be addressed for code quality.

Makefile

A Makefile is provided for convenience:

make install      # Install dependencies
make build       # Build the project
make test        # Run tests
make lint        # Lint the code
make format      # Format the code
make clean       # Clean build artifacts
make publish     # Publish to npm

License

MIT