스크린샷One MCP 서버

ScreenshotOne.com - MCP 서버

이 프로젝트는 AI 어시스턴트를 ScreenshotOne.com API에 연결하여 웹사이트의 스크린샷을 캡처하는 MCP(Model Context Protocol) 서버를 제공합니다.

사용 가능한 기능

[x] 모든 URL의 스크린샷을 찍습니다.
[x] HTML 콘텐츠를 렌더링하고 스크린샷을 찍습니다.
[x] 뷰포트 크기 및 장치 에뮬레이션 사용자 정의
[x] 전체 페이지 스크린샷 캡처
[x] CSS 선택기를 사용하여 특정 요소 선택
[x] 다양한 출력 형식(PNG, JPEG, WebP, PDF)
[x] 광고, 추적기 및 쿠키 배너 차단
[x] 사용자 정의 CSS 및 JavaScript 삽입
[x] 대기 동작 및 타이밍 제어

스크린샷원닷컴

웹사이트
운동장
API 문서
여기에서 API 키를 생성하세요

지원되는 전송

[x] "stdio" 전송 - CLI 사용을 위한 기본 전송
[x]"스트리밍 가능한 HTTP" 전송 - 웹 기반 클라이언트용
- [ ] Bearer <token> 포함한 auth("Authorization" 헤더) 구현
[ ] ~~"sse" 운송~~ (더 이상 사용되지 않음)
[ ] 테스트 작성

사용 방법

CLI

지엑스피1

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(Model Context Protocol)는 AI 시스템이 외부 도구 및 데이터 소스와 안전하고 상황에 맞게 연결할 수 있도록 하는 개방형 표준입니다.

이 보일러플레이트는 모든 API나 데이터 소스에 대한 사용자 정의 MCP 서버를 구축하기 위해 확장 가능한 깔끔하고 계층화된 아키텍처로 MCP 사양을 구현합니다.

왜 이 보일러플레이트를 사용해야 하나요?

프로덕션 준비 아키텍처 : CLI, 도구, 컨트롤러 및 서비스를 명확하게 구분하여 게시된 MCP 서버에서 사용되는 것과 동일한 패턴을 따릅니다.
유형 안전성 : 개발자 경험, 코드 품질, 유지 관리 용이성을 개선하기 위해 TypeScript로 구축되었습니다.
실제 예제 : CLI에서 API 통합까지의 전체 패턴을 보여주는 완전히 구현된 IP 조회 도구가 포함되어 있습니다.
테스트 프레임워크 : 커버리지 보고를 포함하여 단위 및 CLI 통합 테스트를 위한 테스트 인프라가 제공됩니다.
개발 도구 : MCP 서버 개발을 위해 사전 구성된 ESLint, Prettier, TypeScript 및 기타 고품질 도구가 포함되어 있습니다.

시작하기

필수 조건

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

또는 Streamable 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 : 마크다운 서식 도우미

개발 가이드

개발 스크립트

# 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_ACCESS_KEY": "value"
		}
	}
}

참고: 이전 버전과의 호환성을 위해 서버는 전체 패키지 이름( screenshotone-mcp-server ) 또는 screenshotone 가 지정되지 않은 패키지 이름( screenshotone-mcp-server )으로 구성된 구성도 인식합니다. 단, 새 구성에는 짧은 screenshotone 키를 사용하는 것이 좋습니다.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

AI 어시스턴트를 ScreenshotOne.com API에 연결하여 뷰포트 크기, 전체 페이지 캡처, 다양한 출력 형식 등의 사용자 정의 옵션을 통해 웹사이트 스크린샷을 캡처합니다.

Related MCP Servers

MCP Screenshot Server
sethbang
-
security
F
license
-
quality
Enables capturing screenshots of web pages and local HTML files through a simple MCP tool interface using Puppeteer with configurable options for dimensions and output paths.
Last updated -
1
0
4
JavaScript
ScreenshotOne MCP Serverofficial
screenshotone
A
security
A
license
A
quality
An official MCP server implementation that allows AI assistants to capture website screenshots through the ScreenshotOne API, enabling visual context from web pages during conversations.
Last updated -
1
4
21
TypeScript
MIT License
Screenshot MCP Server
codingthefuturewithai
-
security
F
license
-
quality
Enables AI tools to capture and process screenshots of a user's screen, allowing AI assistants to see and analyze what the user is looking at through a simple MCP interface.
Last updated -
1
Python
YouTube MCP
tsubouchi
-
security
F
license
-
quality
Automatically captures and processes screenshots from YouTube videos and Shorts at specified intervals, supporting customizable screenshot timing and providing API endpoints for image management.
Last updated -

View all related MCP servers