ScreenshotOne.com - Servidor MCP

Name: ScreenshotOne MCP Server
Author: mrgoonie

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que conecta a los asistentes de IA con la API de ScreenshotOne.com para capturar capturas de pantalla de sitios web.

Funciones disponibles

[x] Toma capturas de pantalla de cualquier URL
[x] Renderizar contenido HTML y tomar capturas de pantalla
[x] Personalizar el tamaño de la ventana gráfica y la emulación del dispositivo
[x] Capturar capturas de pantalla de página completa
[x] Seleccionar elementos específicos usando selectores CSS
[x] Múltiples formatos de salida (PNG, JPEG, WebP, PDF)
[x] Bloquear anuncios, rastreadores y banners de cookies
[x] Inyectar CSS y JavaScript personalizados
[x] Controlar el comportamiento y el tiempo de espera

Captura de pantallaOne.com

Related MCP server: Webpage Screenshot MCP Server

Transportes soportados

[x] Transporte "stdio" : transporte predeterminado para el uso de CLI
[x] Transporte"HTTP transmitible" : para clientes web
- [ ] Implementar autenticación (encabezados "Autorización" con Bearer <token> )
[ ] ~~transporte "sse"~~ (Obsoleto)
[ ] Escribir pruebas

Cómo utilizar

CLI

# 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

Configuración de MCP

Para la configuración local con transporte stdio:

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

Para la configuración HTTP remota:

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

Variables de entorno para el transporte HTTP:

Puede configurar el servidor HTTP utilizando estas variables de entorno:

MCP_HTTP_HOST : El host al que vincularse (predeterminado: 127.0.0.1 )
MCP_HTTP_PORT : El puerto para escuchar (predeterminado: 8080 )
MCP_HTTP_PATH : La ruta del punto final (predeterminado: /mcp )

Descripción general del código fuente

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite a los sistemas de IA conectarse de forma segura y contextual con herramientas y fuentes de datos externas.

Esta plantilla implementa la especificación MCP con una arquitectura limpia y en capas que puede ampliarse para crear servidores MCP personalizados para cualquier API o fuente de datos.

¿Por qué utilizar este texto estándar?

Arquitectura lista para producción : sigue el mismo patrón utilizado en los servidores MCP publicados, con una clara separación entre CLI, herramientas, controladores y servicios.
Seguridad de tipos : creado con TypeScript para mejorar la experiencia del desarrollador, la calidad del código y la facilidad de mantenimiento.
Ejemplo de trabajo : incluye una herramienta de búsqueda de IP completamente implementada que demuestra el patrón completo desde la CLI hasta la integración de API.
Marco de pruebas : incluye infraestructura de pruebas para pruebas de integración unitarias y CLI, incluidos informes de cobertura.
Herramientas de desarrollo : incluye ESLint, Prettier, TypeScript y otras herramientas de calidad preconfiguradas para el desarrollo de servidores MCP.

Empezando

Prerrequisitos

Node.js (>=18.x): Descargar
Git : para el control de versiones

Paso 1: Clonar e instalar

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

Paso 2: Ejecutar el servidor de desarrollo

Inicie el servidor en modo de desarrollo con el transporte stdio (predeterminado):

npm run dev:server

O con el transporte HTTP Streamable:

npm run dev:server:http

Esto inicia el servidor MCP con recarga activa y habilita el Inspector MCP en http://localhost:5173 .

⚙️ El servidor proxy escucha en el puerto 6277 🔍 MCP Inspector está en funcionamiento en http://127.0.0.1:6274

Al utilizar el transporte HTTP, el servidor estará disponible en http://127.0.0.1:8080/mcp de forma predeterminada.

Paso 3: Pruebe la herramienta de captura de pantalla

Tome una captura de pantalla usando la 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

Arquitectura

Este modelo sigue un patrón de arquitectura limpio y en capas que separa las preocupaciones y promueve la capacidad de mantenimiento.

Estructura del proyecto

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

Capas y responsabilidades

Capa CLI ( `src/cli/*.cli.ts` )

Propósito : Definir interfaces de línea de comandos que analizan argumentos y llaman a controladores.
Nombre : Los archivos deben llamarse <feature>.cli.ts
Pruebas : pruebas de integración de CLI en <feature>.cli.test.ts

Capa de herramientas ( `src/tools/*.tool.ts` )

Propósito : Definir herramientas MCP con esquemas y descripciones para asistentes de IA.
Nombre : Los archivos deben llamarse <feature>.tool.ts con tipos en <feature>.types.ts
Patrón : Cada herramienta debe usar zod para la validación de argumentos

Capa de controladores ( `src/controllers/*.controller.ts` )

Propósito : Implementar lógica empresarial, manejar errores y dar formato a respuestas.
Nombre : Los archivos deben llamarse <feature>.controller.ts
Patrón : Debe devolver objetos ControllerResponse estandarizados

Capa de servicios ( `src/services/*.service.ts` )

Propósito : Interactuar con API externas o fuentes de datos
Nombre : Los archivos deben llamarse <feature>.service.ts
Patrón : Interacciones de API puras con lógica mínima

Capa de utilidades ( `src/utils/*.util.ts` )

Propósito : Proporcionar funcionalidad compartida en toda la aplicación.
Utilidades clave :
- logger.util.ts : Registro estructurado
- error.util.ts : Manejo de errores y estandarización
- formatter.util.ts : ayudantes de formato Markdown

Guía de desarrollo

Scripts de desarrollo

# 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]

Pruebas

# Run all tests npm test # Run specific tests npm test -- src/path/to/test.ts # Generate test coverage report npm run test:coverage

Calidad del código

# Lint code npm run lint # Format code with Prettier npm run format # Check types npm run typecheck

Creación de herramientas personalizadas

Siga estos pasos para agregar sus propias herramientas al servidor:

1. Definir la capa de servicio

Cree un nuevo servicio en src/services/ para interactuar con su API externa:

// 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. Crear controlador

Agregue un controlador en src/controllers/ para manejar la lógica empresarial:

// 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. Implementar la herramienta MCP

Crea una definición de herramienta en 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. Agregar compatibilidad con CLI

Cree un comando CLI en src/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. Registrar componentes

Actualice los puntos de entrada para registrar sus nuevos componentes:

// 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);

Herramientas de depuración

Inspector de MCP

Acceda al Inspector visual de MCP para probar sus herramientas y ver los detalles de la solicitud/respuesta:

Ejecutar npm run dev:server
Abra http://localhost:5173 en su navegador
Pruebe sus herramientas y vea los registros directamente en la interfaz de usuario

Registros del servidor

Habilitar registros de depuración para el desarrollo:

# Set environment variable DEBUG=true npm run dev:server # Or configure in ~/.mcp/configs.json

Publicación de su servidor MCP

Cuando esté listo para publicar su servidor MCP personalizado:

Actualice package.json con sus datos
Actualice README.md con la documentación de su herramienta
Construya el proyecto: npm run build
Pruebe la compilación de producción: npm run start:server
Publicar en npm: npm publish

Licencia

Licencia ISC

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

Nota: Para compatibilidad con versiones anteriores, el servidor también reconocerá las configuraciones con el nombre completo del paquete ( screenshotone-mcp-server ) o con el nombre sin ámbito ( screenshotone-mcp-server ) si no se encuentra la clave screenshotone . Sin embargo, se recomienda usar la clave corta screenshotone para las nuevas configuraciones.