スクリーンショットOne MCPサーバー

ScreenshotOne.com - MCP サーバー

このプロジェクトは、AI アシスタントをScreenshotOne.com API に接続して Web サイトのスクリーンショットをキャプチャする Model Context Protocol (MCP) サーバーを提供します。

利用可能な機能

[x] 任意のURLのスクリーンショットを撮る
[x] HTMLコンテンツをレンダリングし、スクリーンショットを撮る
[x] ビューポートサイズとデバイスエミュレーションをカスタマイズする
[x] 全ページのスクリーンショットをキャプチャする
[x] CSSセレクターを使用して特定の要素を選択する
[x] 複数の出力形式（PNG、JPEG、WebP、PDF）
[x] 広告、トラッカー、Cookieバナーをブロックする
[x] カスタムCSSとJavaScriptを挿入する
[x] 待機動作とタイミングを制御する

スクリーンショットワン

Webサイト
遊び場
APIドキュメント
ここでAPIキーを作成してください

サポートされているトランスポート

[x] "stdio"トランスポート - CLI 使用時のデフォルトのトランスポート
[x]「ストリーミング可能なHTTP」トランスポート - Webベースのクライアント向け
- [ ] 認証を実装する（ Bearer <token>を使用した「Authorization」ヘッダー）
[ ] ~~「sse」輸送~~(非推奨)
[ ] テストを書く

使い方

コマンドライン

# Take a screenshot of a URL
npm run dev:cli -- take-screenshot --url "https://example.com" --access-key "your-access-key"

# Take a screenshot with custom viewport
npm run dev:cli -- take-screenshot --url "https://example.com" --viewport-width 1920 --viewport-height 1080

# Capture a full page screenshot
npm run dev:cli -- take-screenshot --url "https://example.com" --full-page

# Save the screenshot to a file
npm run dev:cli -- take-screenshot --url "https://example.com" --output screenshot.png

# Block ads and trackers
npm run dev:cli -- take-screenshot --url "https://example.com" --block-ads --block-trackers --block-cookie-banners

# ----------------------------------------------
# UPLOAD SCREENSHOT TO CLOUDFLARE
# REMEMBER TO SET THE ENVIRONMENT VARIABLES
# > See example at ".env.example" file
# ----------------------------------------------

# Take a screenshot and upload it to Cloudflare
npm run dev:cli -- take-screenshot --url https://example.com --upload

# Take a screenshot with a custom filename
npm run dev:cli -- take-screenshot --url https://example.com --upload --upload-filename my-screenshot

# Take a screenshot with upload debugging enabled
npm run dev:cli -- take-screenshot --url https://example.com --upload --upload-debug

MCPセットアップ

stdio トランスポートを使用したローカル構成の場合:

{
  "mcpServers": {
    "screenshotone": {
      "command": "node",
      "args": ["/path/to/screenshotone-mcp-server/dist/index.js"],
      "transportType": "stdio"
    }
  }
}

リモート HTTP 構成の場合:

{
  "mcpServers": {
    "screenshotone": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

HTTP トランスポートの環境変数:

次の環境変数を使用して HTTP サーバーを構成できます。

MCP_HTTP_HOST : バインドするホスト（デフォルト: 127.0.0.1 ）
MCP_HTTP_PORT : リッスンするポート（デフォルト: 8080 ）
MCP_HTTP_PATH : エンドポイントパス（デフォルト: /mcp ）

ソースコードの概要

MCPとは何ですか?

モデルコンテキストプロトコル (MCP) は、AI システムが外部ツールやデータソースに安全かつコンテキストに応じて接続できるようにするオープンスタンダードです。

このボイラープレートは、任意の API またはデータソース用のカスタム MCP サーバーを構築するために拡張できる、クリーンな階層化アーキテクチャを使用して MCP 仕様を実装します。

この定型句を使用する理由

実稼働対応アーキテクチャ: 公開された MCP サーバーで使用されるのと同じパターンに従い、CLI、ツール、コントローラー、およびサービスが明確に分離されています。
型の安全性: 開発者エクスペリエンス、コード品質、保守性を向上させるために TypeScript を使用して構築されています。
動作例: CLI から API 統合までの完全なパターンを示す、完全に実装された IP 検索ツールが含まれています。
テストフレームワーク: カバレッジレポートを含む、ユニットテストと CLI 統合テストの両方のテストインフラストラクチャが付属しています。
開発ツール: ESLint、Prettier、TypeScript、および MCP サーバー開発用に事前構成されたその他の高品質ツールが含まれています。

はじめる

前提条件

Node.js (>=18.x):ダウンロード
Git : バージョン管理用

ステップ1: クローンとインストール

# Clone the repository
git clone https://github.com/mrgoonie/screenshotone-mcp-server.git
cd screenshotone-mcp-server

# Install dependencies
npm install

ステップ2: 開発サーバーを実行する

stdio トランスポートを使用して開発モードでサーバーを起動します (デフォルト)。

npm run dev:server

または、ストリーミング可能な HTTP トランスポートを使用する場合:

npm run dev:server:http

これにより、ホットリロードで MCP サーバーが起動し、 http://localhost:5173で MCP インスペクターが有効になります。

⚙️ プロキシサーバーはポート 6277 で待機しています 🔍 MCP Inspector はhttp://127.0.0.1:6274で稼働しています

HTTP トランスポートを使用する場合、サーバーはデフォルトでhttp://127.0.0.1:8080/mcpで利用できるようになります。

ステップ3: スクリーンショットツールをテストする

CLI を使用してスクリーンショットを撮ります。

# Basic screenshot
npm run dev:cli -- take-screenshot --url "https://example.com" --access-key "your-access-key"

# Advanced options
npm run dev:cli -- take-screenshot --url "https://example.com" --format png --viewport-width 1920 --viewport-height 1080 --full-page --output screenshot.png

建築

このボイラープレートは、懸念事項を分離し、保守性を促進する、クリーンな階層化アーキテクチャパターンに従います。

プロジェクト構造

src/
├── cli/              # Command-line interfaces
├── controllers/      # Business logic
├── resources/        # MCP resources: expose data and content from your servers to LLMs
├── services/         # External API interactions
├── tools/            # MCP tool definitions
├── types/            # Type definitions
├── utils/            # Shared utilities
└── index.ts          # Entry point

階層と責任

CLI レイヤー ( `src/cli/*.cli.ts` )

目的: 引数を解析してコントローラを呼び出すコマンドラインインターフェースを定義する
命名: ファイル名は<feature>.cli.tsとします
テスト: <feature>.cli.test.ts内の CLI 統合テスト

ツールレイヤー ( `src/tools/*.tool.ts` )

目的: AIアシスタント用のスキーマと説明を備えたMCPツールを定義する
命名: ファイルは<feature>.tool.tsという名前にし、型は<feature>.types.tsに記述します。
パターン: 各ツールは引数の検証に zod を使用する必要があります

コントローラーレイヤー ( `src/controllers/*.controller.ts` )

目的: ビジネスロジックを実装し、エラーを処理し、応答をフォーマットする
命名: ファイル名は<feature>.controller.tsとします
パターン: 標準化されたControllerResponseオブジェクトを返す必要があります

サービス層 ( `src/services/*.service.ts` )

目的: 外部APIまたはデータソースとのやり取り
命名: ファイル名は<feature>.service.tsとします
パターン: 最小限のロジックによる純粋な API のインタラクション

ユーティリティ層 ( `src/utils/*.util.ts` )

目的: アプリケーション全体で共有機能を提供する
キーユーティリティ:
- logger.util.ts : 構造化ログ
- error.util.ts : エラー処理と標準化
- formatter.util.ts : Markdown フォーマットヘルパー

開発ガイド

開発スクリプト

# Start server in development mode (hot-reload & inspector)
npm run dev:server

# Run CLI in development mode
npm run dev:cli -- [command] [args]

# Build the project
npm run build

# Start server in production mode
npm run start:server

# Run CLI in production mode
npm run start:cli -- [command] [args]

テスト

# Run all tests
npm test

# Run specific tests
npm test -- src/path/to/test.ts

# Generate test coverage report
npm run test:coverage

コード品質

# Lint code
npm run lint

# Format code with Prettier
npm run format

# Check types
npm run typecheck

カスタムツールの構築

独自のツールをサーバーに追加するには、次の手順に従います。

1. サービス層を定義する

外部 API と対話するためにsrc/services/に新しいサービスを作成します。

// src/services/example.service.ts
import { Logger } from '../utils/logger.util.js';

const logger = Logger.forContext('services/example.service.ts');

export async function getData(param: string): Promise<any> {
	logger.debug('Getting data', { param });
	// API interaction code here
	return { result: 'example data' };
}

2. コントローラーを作成する

ビジネスロジックを処理するために、 src/controllers/にコントローラーを追加します。

// src/controllers/example.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as exampleService from '../services/example.service.js';
import { formatMarkdown } from '../utils/formatter.util.js';
import { handleControllerError } from '../utils/error-handler.util.js';
import { ControllerResponse } from '../types/common.types.js';

const logger = Logger.forContext('controllers/example.controller.ts');

export interface GetDataOptions {
	param?: string;
}

export async function getData(
	options: GetDataOptions = {},
): Promise<ControllerResponse> {
	try {
		logger.debug('Getting data with options', options);

		const data = await exampleService.getData(options.param || 'default');

		const content = formatMarkdown(data);

		return { content };
	} catch (error) {
		throw handleControllerError(error, {
			entityType: 'ExampleData',
			operation: 'getData',
			source: 'controllers/example.controller.ts',
		});
	}
}

3. MCPツールを実装する

src/tools/にツール定義を作成します。

// src/tools/example.tool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { Logger } from '../utils/logger.util.js';
import { formatErrorForMcpTool } from '../utils/error.util.js';
import * as exampleController from '../controllers/example.controller.js';

const logger = Logger.forContext('tools/example.tool.ts');

const GetDataArgs = z.object({
	param: z.string().optional().describe('Optional parameter'),
});

type GetDataArgsType = z.infer<typeof GetDataArgs>;

async function handleGetData(args: GetDataArgsType) {
	try {
		logger.debug('Tool get_data called', args);

		const result = await exampleController.getData({
			param: args.param,
		});

		return {
			content: [{ type: 'text' as const, text: result.content }],
		};
	} catch (error) {
		logger.error('Tool get_data failed', error);
		return formatErrorForMcpTool(error);
	}
}

export function register(server: McpServer) {
	server.tool(
		'get_data',
		`Gets data from the example API, optionally using \`param\`.
Use this to fetch example data. Returns formatted data as Markdown.`,
		GetDataArgs.shape,
		handleGetData,
	);
}

4. CLIサポートを追加する

src/cli/に CLI コマンドを作成します。

// src/cli/example.cli.ts
import { program } from 'commander';
import { Logger } from '../utils/logger.util.js';
import * as exampleController from '../controllers/example.controller.js';
import { handleCliError } from '../utils/error-handler.util.js';

const logger = Logger.forContext('cli/example.cli.ts');

program
	.command('get-data')
	.description('Get example data')
	.option('--param <value>', 'Optional parameter')
	.action(async (options) => {
		try {
			logger.debug('CLI get-data called', options);

			const result = await exampleController.getData({
				param: options.param,
			});

			console.log(result.content);
		} catch (error) {
			handleCliError(error);
		}
	});

5. コンポーネントを登録する

新しいコンポーネントを登録するには、エントリポイントを更新します。

// In src/cli/index.ts
import '../cli/example.cli.js';

// In src/index.ts (for the tool)
import exampleTool from './tools/example.tool.js';
// Then in registerTools function:
exampleTool.register(server);

デバッグツール

MCP検査官

ビジュアル MCP インスペクターにアクセスしてツールをテストし、リクエスト/レスポンスの詳細を表示します。

npm run dev:server実行します。
ブラウザでhttp://localhost:5173を開きます。
ツールをテストし、UI で直接ログを表示します

サーバーログ

開発用のデバッグログを有効にします。

# Set environment variable
DEBUG=true npm run dev:server

# Or configure in ~/.mcp/configs.json

MCPサーバーの公開

カスタム MCP サーバーを公開する準備ができたら、次の手順を実行します。

詳細を記載したpackage.jsonを更新します
ツールのドキュメントをREADME.mdに更新する
プロジェクトをビルドします: npm run build
本番ビルドをテストする: npm run start:server
npmに公開: npm publish

ライセンス

ISCライセンス

{
	"screenshotone": {
		"environments": {
			"DEBUG": "true",
			"SCREENSHOTONE_API_KEY": "value"
		}
	}
}

**注:**後方互換性のため、 screenshotoneキーが見つからない場合、サーバーは完全なパッケージ名 ( screenshotone-mcp-server ) またはスコープ外のパッケージ名 ( screenshotone-mcp-server ) の設定も認識します。ただし、新しい設定では短縮形のscreenshotoneキーの使用が推奨されます。

Integrations