该项目提供了一个模型上下文协议 (MCP) 服务器，将 AI 助手连接到ScreenshotOne.com API 以捕获网站的屏幕截图。
可用功能
- [x] 对任何 URL 进行截图
- [x] 渲染 HTML 内容并截取屏幕截图
- [x] 自定义视口大小和设备模拟
- [x] 截取整页截图
- [x] 使用 CSS 选择器选择特定元素
- [x] 多种输出格式（PNG、JPEG、WebP、PDF）
- [x] 屏蔽广告、跟踪器和 Cookie 横幅
- [x] 注入自定义 CSS 和 JavaScript
- [x] 控制等待行为和时间
ScreenshotOne.com
支持的传输
- [x] “stdio”传输 - CLI 使用的默认传输
- [x]“可流式传输 HTTP”传输 - 适用于基于 Web 的客户端
- [ ] 实现身份验证（“授权”标头带有
Bearer <token> ）
- [ ]
“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 系统安全且上下文地与外部工具和数据源连接。
该样板通过清晰的分层架构实现了 MCP 规范，可以扩展以构建任何 API 或数据源的自定义 MCP 服务器。
为什么要使用这个样板？
- 生产就绪架构：遵循已发布的 MCP 服务器中使用的相同模式，CLI、工具、控制器和服务之间有明确的分离。
- 类型安全：使用 TypeScript 构建，以改善开发人员体验、代码质量和可维护性。
- 工作示例：包括一个完全实现的 IP 查找工具，演示从 CLI 到 API 集成的完整模式。
- 测试框架：配备单元和 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 传输（默认）以开发模式启动服务器：
或者使用 Streamable 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 集成测试
- 目的：为人工智能助手定义带有模式和描述的 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.定义服务层
在src/services/中创建一个新服务来与您的外部 API 交互：
// 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键。