feat: MCP server implementation (#1)

* Implementation of MCP server for Apify Actors
---------

Co-authored-by: František Nesveda <fnesveda@users.noreply.github.com>

Author: jirispilka

.actor/Dockerfile

@@ -0,0 +1,57 @@
+# Specify the base Docker image. You can read more about
+# the available images at https://docs.apify.com/sdk/js/docs/guides/docker-images
+# You can also use any other image from Docker Hub.
+FROM apify/actor-node:20 AS builder
+
+# Check preinstalled packages
+RUN npm ls crawlee apify puppeteer playwright
+
+# Copy just package.json and package-lock.json
+# to speed up the build using Docker layer cache.
+COPY package*.json ./
+
+# Install all dependencies. Don't audit to speed up the installation.
+RUN npm install --include=dev --audit=false
+
+# Next, copy the source files using the user set
+# in the base image.
+COPY . ./
+
+# Install all dependencies and build the project.
+# Don't audit to speed up the installation.
+RUN npm run build
+
+# Create final image
+FROM apify/actor-node:20
+
+# Check preinstalled packages
+RUN npm ls crawlee apify puppeteer playwright
+
+# Copy just package.json and package-lock.json
+# to speed up the build using Docker layer cache.
+COPY package*.json ./
+
+# Install NPM packages, skip optional and development dependencies to
+# keep the image small. Avoid logging too much and print the dependency
+# tree for debugging
+RUN npm --quiet set progress=false \
+    && npm install --omit=dev --omit=optional \
+    && echo "Installed NPM packages:" \
+    && (npm list --omit=dev --all || true) \
+    && echo "Node.js version:" \
+    && node --version \
+    && echo "NPM version:" \
+    && npm --version \
+    && rm -r ~/.npm
+
+# Copy built JS files from builder image
+COPY --from=builder /usr/src/app/dist ./dist
+
+# Next, copy the remaining files and directories with the source code.
+# Since we do this after NPM install, quick build will be really fast
+# for most source file changes.
+COPY . ./
+
+
+# Run the image.
+CMD npm run start:prod --silent

.actor/actor.json

@@ -0,0 +1,9 @@
+{
+  "actorSpecification": 1,
+  "name": "apify-mcp-server",
+  "title": "Model Context Protocol Server for Apify Actors",
+  "description": "Implementation of a Model Context Protocol (MCP) Server for Apify Actors that enables AI applications (and AI agents) to interact with Apify Actors",
+  "version": "0.0",
+  "input": "./input_schema.json",
+  "dockerfile": "./Dockerfile"
+}

.actor/input_schema.json

@@ -0,0 +1,35 @@
+{
+    "title": "Apify MCP Server",
+    "type": "object",
+    "schemaVersion": 1,
+    "properties": {
+        "actors": {
+            "title": "Actors to be exposed for an AI application (AI agent)",
+            "type": "array",
+            "description": "List Actors to be exposed to an AI application (AI agent) for communication via the MCP protocol. \n\n Ensure the Actor definitions fit within the LLM context by limiting the number of used Actors.",
+            "editor": "stringList",
+            "prefill": [
+                "apify/instagram-scraper",
+                "apify/rag-web-browser",
+                "lukaskrivka/google-maps-with-contact-details"
+            ]
+        },
+        "debugActor": {
+            "title": "Debug Actor",
+            "type": "string",
+            "description": "Specify the name of the Actor that will be used for debugging in normal mode",
+            "editor": "textfield",
+            "prefill": "apify/rag-web-browser",
+            "sectionCaption": "Debugging settings (normal mode)"
+        },
+        "debugActorInput": {
+            "title": "Debug Actor input",
+            "type": "object",
+            "description": "Specify the input for the Actor that will be used for debugging in normal mode",
+            "editor": "json",
+            "prefill": {
+                "query": "hello world"
+            }
+        }
+    }
+}

.dockerignore

@@ -16,3 +16,4 @@ node_modules
 data
 src/storage
 dist
+.env

.env.example

@@ -0,0 +1,3 @@
+APIFY_TOKEN=
+# ANTHROPIC_API_KEY is only required when you want to run examples/clientStdioChat.js
+ANTHROPIC_API_KEY=

.github/scripts/before-beta-release.js

@@ -0,0 +1,32 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const PKG_JSON_PATH = path.join(__dirname, '..', '..', 'package.json');
+
+const pkgJson = require(PKG_JSON_PATH); // eslint-disable-line import/no-dynamic-require
+
+const PACKAGE_NAME = pkgJson.name;
+const VERSION = pkgJson.version;
+
+const nextVersion = getNextVersion(VERSION);
+console.log(`before-deploy: Setting version to ${nextVersion}`); // eslint-disable-line no-console
+pkgJson.version = nextVersion;
+
+fs.writeFileSync(PKG_JSON_PATH, `${JSON.stringify(pkgJson, null, 2)}\n`);
+
+function getNextVersion(version) {
+    const versionString = execSync(`npm show ${PACKAGE_NAME} versions --json`, { encoding: 'utf8' });
+    const versions = JSON.parse(versionString);
+
+    if (versions.some((v) => v === VERSION)) {
+        console.error(`before-deploy: A release with version ${VERSION} already exists. Please increment version accordingly.`); // eslint-disable-line no-console
+        process.exit(1);
+    }
+
+    const prereleaseNumbers = versions
+        .filter((v) => (v.startsWith(VERSION) && v.includes('-')))
+        .map((v) => Number(v.match(/\.(\d+)$/)[1]));
+    const lastPrereleaseNumber = Math.max(-1, ...prereleaseNumbers);
+    return `${version}-beta.${lastPrereleaseNumber + 1}`;
+}

.github/workflows/check.yaml

@@ -0,0 +1,30 @@
+# This workflow runs for every pull request to lint and test the proposed changes.
+
+name: Check
+
+on:
+    pull_request:
+
+    # Push to master will trigger code checks
+    push:
+        branches:
+            - master
+        tags-ignore:
+            - "**" # Ignore all tags to prevent duplicate builds when tags are pushed.
+
+jobs:
+    lint:
+        name: Lint
+        runs-on: ubuntu-latest
+
+        steps:
+            -   uses: actions/checkout@v4
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+                    cache: 'npm'
+                    cache-dependency-path: 'package-lock.json'
+            -   name: Install Dependencies
+                run: npm ci
+            -   run: npm run lint

.github/workflows/pre_release.yaml

@@ -0,0 +1,103 @@
+name: Create a pre-release
+
+on:
+    # Push to master will deploy a beta version
+    push:
+        branches:
+            - master
+        tags-ignore:
+            - "**" # Ignore all tags to prevent duplicate builds when tags are pushed.
+
+concurrency:
+    group: release
+    cancel-in-progress: false
+
+jobs:
+    release_metadata:
+        if: "!startsWith(github.event.head_commit.message, 'docs') && !startsWith(github.event.head_commit.message, 'ci') && startsWith(github.repository, 'apify/')"
+        name: Prepare release metadata
+        runs-on: ubuntu-latest
+        outputs:
+            version_number: ${{ steps.release_metadata.outputs.version_number }}
+            changelog: ${{ steps.release_metadata.outputs.changelog }}
+        steps:
+            -   uses: apify/workflows/git-cliff-release@main
+                name: Prepare release metadata
+                id: release_metadata
+                with:
+                    release_type: prerelease
+                    existing_changelog_path: CHANGELOG.md
+
+    wait_for_checks:
+        name: Wait for code checks to pass
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: lewagon/wait-on-check-action@v1.3.4
+                with:
+                    ref: ${{ github.ref }}
+                    repo-token: ${{ secrets.GITHUB_TOKEN }}
+                    check-name: 'Lint'
+                    wait-interval: 5
+
+    update_changelog:
+        needs: [ release_metadata ]
+        name: Update changelog
+        runs-on: ubuntu-latest
+        outputs:
+            changelog_commitish: ${{ steps.commit.outputs.commit_long_sha || github.sha }}
+
+        steps:
+            -   name: Checkout repository
+                uses: actions/checkout@v4
+                with:
+                    token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
+
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+
+            -   name: Update package version in package.json
+                run: npm version --no-git-tag-version --allow-same-version ${{ needs.release_metadata.outputs.version_number }}
+
+            -   name: Update CHANGELOG.md
+                uses: DamianReeves/write-file-action@master
+                with:
+                    path: CHANGELOG.md
+                    write-mode: overwrite
+                    contents: ${{ needs.release_metadata.outputs.changelog }}
+
+            -   name: Commit changes
+                id: commit
+                uses: EndBug/add-and-commit@v9
+                with:
+                    author_name: Apify Release Bot
+                    author_email: noreply@apify.com
+                    message: "chore(release): Update changelog and package version [skip ci]"
+
+    publish_to_npm:
+        name: Publish to NPM
+        needs: [ release_metadata ]
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: actions/checkout@v4
+                with:
+                    ref: ${{ needs.update_changelog.changelog_commitish }}
+            -   name: Use Node.js 22
+                uses: actions/setup-node@v4
+                with:
+                    node-version: 22
+            -   name: Install dependencies
+                run: |
+                    echo "access=public" >> .npmrc
+                    echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> .npmrc
+                    npm install
+            - # Check version consistency and increment pre-release version number for beta only.
+                name: Bump pre-release version
+                run: node ./.github/scripts/before-beta-release.js
+            -   name: Publish to NPM
+                run: npm publish --tag beta
+
+env:
+    NODE_AUTH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}
+    NPM_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_NPM_TOKEN }}