ScreenshotOne.com - MCP 服务器

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

• Github
• NPM

可用功能

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

ScreenshotOne.com

• 官网
• 游乐场
• API文档
• 在这里创建您的API密钥

支持的传输方式

• "stdio" 传输 - CLI使用的默认传输
• "Streamable HTTP" 传输 - 适用于基于Web的客户端
  • 实现认证 ("Authorization" 标头带有 Bearer <token>)
• ~~"sse" 传输~~ (已弃用)
• 编写测试

如何使用

命令行界面 (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): 下载
• 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 {
logger.debug('Getting data', { param });
// 在此处编写 API 交互代码
return { result: 'example data' };
}

2. 创建控制器

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

typescript
// 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 {
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/ 中创建工具定义：

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

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 命令：

typescript
// 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 ', '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. 注册组件

更新入口点以注册新组件：

typescript
// 在 src/cli/index.ts 中
import '../cli/example.cli.js';

// 在 src/index.ts 中（针对工具）
import exampleTool from './tools/example.tool.js';
// 然后在 registerTools 函数中：
exampleTool.register(server);---

调试工具

MCP 检查器

访问可视化 MCP 检查器以测试您的工具并查看请求/响应详情：

1. 运行 npm run dev:server
2. 在浏览器中打开 http://localhost:5173
3. 直接在 UI 中测试您的工具并查看日志

服务器日志

启用开发调试日志：

bash

设置环境变量

DEBUG=true npm run dev:server

或者在 ~/.mcp/configs.json 中配置

---

发布您的 MCP 服务器

当您准备好发布自定义的 MCP 服务器时：

1. 使用您的详细信息更新 package.json
2. 更新 README.md，添加您的工具文档
3. 构建项目：npm run build
4. 测试生产构建：npm run start:server
5. 发布到 npm：npm publish

---

许可证

ISC 许可证

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

注意： 为了向后兼容，如果未找到 screenshotone 键，服务器也会识别完整包名（screenshotone-mcp-server）或非作用域包名（screenshotone-mcp-server）下的配置。但是，对于新配置，建议使用简短的 screenshotone 键。