# ScreenshotOne截图工具
## 基本信息
- Slug: `mrgoonie-screenshotone-mcp-server`
- Source: modelscope
- Publisher: @mrgoonie/screenshotone-mcp-server
- Categories: browser-automation / web-scraping / app-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@mrgoonie/screenshotone-mcp-server
## 简介
将AI助手连接到ScreenshotOne.com API，以捕获网站截图。该API提供可自定义选项，包括视口大小、全页捕捉和多种输出格式。
## MCP Server 详情

# ScreenshotOne.com - MCP 服务器

该项目提供了一个模型上下文协议（MCP）服务器，用于将AI助手连接到[ScreenshotOne.com](https://screenshotone.com) API以捕获网站的屏幕截图。

- [Github](https://github.com/mrgoonie/screenshotone-mcp-server)
- [NPM](https://www.npmjs.com/package/screenshotone-mcp-server)

### 可用功能
- [x] 捕获任何URL的屏幕截图
- [x] 渲染HTML内容并截取屏幕截图
- [x] 自定义视口大小和设备模拟
- [x] 捕获全页面屏幕截图
- [x] 使用CSS选择器选择特定元素
- [x] 多种输出格式 (PNG, JPEG, WebP, PDF)
- [x] 阻止广告、跟踪器和Cookie横幅
- [x] 注入自定义CSS和JavaScript
- [x] 控制等待行为和时间

## ScreenshotOne.com

- [官网](https://screenshotone.com)
- [游乐场](https://screenshotone.com/playground)
- [API文档](https://screenshotone.com/docs/getting-started/)
- 在[这里](https://dash.screenshotone.com/access)创建您的API密钥

## 支持的传输方式

- [x] ["stdio"](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio) 传输 - CLI使用的默认传输
- [x] ["Streamable HTTP"](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 传输 - 适用于基于Web的客户端
  - [ ] 实现认证 ("Authorization" 标头带有 `Bearer <token>`)
- [ ] ~~"sse" 传输~~ **[(已弃用)](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility)**
- [ ] 编写测试

## 如何使用

### 命令行界面 (CLI)

bash
# 捕获一个URL的屏幕截图
npm run dev:cli -- take-screenshot --url "https://example.com" --access-key "your-access-key"

# 使用自定义视口捕获屏幕截图
npm run dev:cli -- take-screenshot --url "https://example.com" --viewport-width 1920 --viewport-height 1080

# 捕获全页面屏幕截图
npm run dev:cli -- take-screenshot --url "https://example.com" --full-page

# 将屏幕截图保存到文件
npm run dev:cli -- take-screenshot --url "https://example.com" --output screenshot.png

# 阻止广告和跟踪器
npm run dev:cli -- take-screenshot --url "https://example.com" --block-ads --block-trackers --block-cookie-banners

# ----------------------------------------------
# 将屏幕截图上传到Cloudflare
# 记得设置环境变量
# > 请参见 ".env.example" 文件
# ----------------------------------------------

# 捕获屏幕截图并上传到Cloudflare
npm run dev:cli -- take-screenshot --url https://example.com --upload

# 使用自定义文件名捕获屏幕截图
npm run dev:cli -- take-screenshot --url https://example.com --upload --upload-filename my-screenshot

# 启用上传调试捕获屏幕截图
npm run dev:cli -- take-screenshot --url https://example.com --upload --upload-debug


### MCP 设置

**对于使用stdio传输的本地配置：**
json
{
  "mcpServers": {
    "screenshotone": {
      "command": "node",
      "args": ["/path/to/screenshotone-mcp-server/dist/index.js"],
      "transportType": "stdio"
    }
  }
}


**对于远程HTTP配置：**
json
{
  "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系统安全且有上下文地连接到外部工具和数据源。

此模板实现了MCP规范，并具有清晰的分层架构，可以扩展以构建针对任何API或数据源的自定义MCP服务器。

## 为什么使用此模板？- **生产就绪架构**：遵循已发布的MCP服务器中使用的相同模式，清晰地分离了CLI、工具、控制器和服务。

- **类型安全**：使用TypeScript构建，以提高开发体验、代码质量和可维护性。

- **工作示例**：包含一个完全实现的IP查找工具，展示了从CLI到API集成的完整模式。

- **测试框架**：附带单元测试和CLI集成测试的基础架构，包括覆盖率报告。

- **开发工具**：预配置了ESLint、Prettier、TypeScript等质量工具，适用于MCP服务器开发。

---

# 入门指南

## 前提条件

- **Node.js** (>=18.x): [下载](https://nodejs.org/)
- **Git**: 用于版本控制

---

## 步骤1：克隆并安装

bash
# 克隆仓库
git clone https://github.com/mrgoonie/screenshotone-mcp-server.git
cd screenshotone-mcp-server

# 安装依赖
npm install


---

## 步骤2：运行开发服务器

使用stdio传输（默认）在开发模式下启动服务器：

bash
npm run dev:server


或者使用Streamable HTTP传输：

bash
npm run dev:server:http


这将以热重载方式启动MCP服务器，并启用位于http://localhost:5173的MCP Inspector。

⚙️ 代理服务器监听端口6277
🔍 MCP Inspector正在运行于http://127.0.0.1:6274

当使用HTTP传输时，默认情况下服务器将可在http://127.0.0.1:8080/mcp访问。

---

## 步骤3：测试截图工具

使用CLI进行截图：

bash
# 基本截图
npm run dev:cli -- take-screenshot --url "https://example.com" --access-key "your-access-key"

# 高级选项
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/              # 命令行接口
├── controllers/      # 业务逻辑
├── resources/        # MCP资源：向LLMs暴露来自您服务器的数据和内容
├── services/         # 外部API交互
├── tools/            # MCP工具定义
├── types/            # 类型定义
├── utils/            # 共享实用程序
└── index.ts          # 入口点


## 层次及职责

### CLI层 (`src/cli/*.cli.ts`)

- **目的**：定义解析参数并调用控制器的命令行接口
- **命名**：文件应命名为`<feature>.cli.ts`
- **测试**：CLI集成测试位于`<feature>.cli.test.ts`

### 工具层 (`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格式化辅助函数

---

# 开发指南

## 开发脚本

bash
# 在开发模式下启动服务器（热重载&检查器）
npm run dev:server

# 在开发模式下运行CLI
npm run dev:cli -- [command] [args]

# 构建项目
npm run build

# 在生产模式下启动服务器
npm run start:server

# 在生产模式下运行CLI
npm run start:cli -- [command] [args]## 测试

bash
# 运行所有测试
npm test

# 运行特定测试
npm test -- src/path/to/test.ts

# 生成测试覆盖率报告
npm run test:coverage


## 代码质量

bash
# 代码检查
npm run lint

# 使用 Prettier 格式化代码
npm run format

# 检查类型
npm run typecheck


---

# 构建自定义工具

按照以下步骤向服务器添加自己的工具：

## 1. 定义服务层

在 `src/services/` 中创建一个新的服务以与外部 API 交互：

typescript
// 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 交互代码
    return { result: 'example data' };
}


## 2. 创建控制器

在 `src/controllers/` 中添加一个控制器来处理业务逻辑：

typescript
// src/controllers/example.controller.ts
import…