250812 Html Reader MCP Server

HTML API阅读器

使用Rust编写的高性能REST API服务器，用于从网页中获取和提取内容。使用具有工作空间结构的干净架构原则构建。

目录

• 快速开始
• 特性
• API终点
• 建筑
• 建筑
• 跑步
• 项目结构
• 发展
• 错误处理

快速开始

🚀 利用地方发展

1. 构建并运行：

   cargo build --release
   cargo run --bin html-mcp-reader

1. 测试API：

   # Health check
   curl http://localhost:8085/health

   # Fetch web content
   curl -X POST http://localhost:8085/api/fetch \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com"}'

🐳 使用Docker

1. 构建Docker镜像：

   docker build -t html-api-reader:latest .

1. 运行容器：

   docker run -p 8085:8085 html-api-reader:latest

1. 或者使用Docker Compose：

   docker-compose up

特性

• REST API：用于获取web内容的简单HTTP端点
• HTML内容提取：从HTML页面提取文本内容
• 灵活的选项：配置文本提取、重定向、超时和用户代理
• 清洁建筑：对领域驱动设计的独立关注
• 异步/等待：使用Tokio进行高性能异步处理
• CORS支持：启用了跨源请求
• 健康监测：内置健康检查端点
• Docker就绪：带有健康检查的容器化部署

API终点

GET/健康

返回API服务器的运行状况。

答复：

{
  "status": "healthy",
  "version": "0.1.0"
}

POST/api/fetch

从网页中获取和提取内容。

请求正文：

{
  "url": "https://example.com",
  "extract_text_only": true,
  "follow_redirects": true,
  "timeout_seconds": 30,
  "user_agent": "html-api-reader/0.1.0"
}

参数：

• url （必填）：从中获取内容的URL
• extract_text_only （可选，默认值：true）：是否仅提取文本内容
• follow_redirects （可选，默认值：true）：是否遵循HTTP重定向
• timeout_seconds （可选，默认值：30，最大值：300）：请求超时（秒）
• user_agent （可选）：自定义用户代理标头

答复：

{
  "url": "https://example.com",
  "title": "Example Domain",
  "text_content": "Example Domain This domain is for use in illustrative examples...",
  "raw_html": "...",
  "metadata": {
    "content_type": "text/html; charset=utf-8",
    "status_code": 200,
    "content_length": 1256,
    "last_modified": null,
    "charset": null
  }
}

错误响应：

{
  "error": "INVALID_URL",
  "message": "URL cannot be empty"
}

建筑

该项目遵循清洁架构原则，包括以下几层：

• 领域：核心业务逻辑和接口(domain/)
• 应用：用例和业务服务(application/)
• 基础设施：用于HTTP、HTML解析和REST API的外部适配器(infrastructure/)
• 跑者：入口点和依赖注入(runner/)

依赖项

使用的关键依赖关系：

• axum：REST API的现代web框架
• tower-http：HTTP中间件（CORS支持）
• reqwest：用于获取web内容的HTTP客户端
• scraper：HTML解析和文本提取
• serde/serde_json：API请求/响应的JSON序列化
• tracing：结构化日志记录
• tokio：异步运行时

建筑

地方发展

# Build debug version
cargo build

# Build release version (optimized)
cargo build --release

# Run tests
cargo test

# Check code quality
cargo clippy
cargo fmt

码头工人

# Build the Docker image
docker build -t html-api-reader:latest .

# Build with Docker Compose
docker-compose build

跑步

地方发展

# Run in development mode
cargo run --bin html-mcp-reader

# Run release version
./target/release/html-mcp-reader

# Run with custom port
PORT=9000 cargo run --bin html-mcp-reader

服务器将于启动 http://0.0.0.0:8085 默认情况下。

码头工人

# Run with Docker (recommended for production)
docker run -p 8085:8085 html-api-reader:latest

# Run with Docker Compose
docker-compose up

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f html-api-reader

# Stop
docker-compose down

环境变量

• PORT：服务器端口（默认值：8085）
• RUST_LOG：日志级别（默认值：info）
• RUST_BACKTRACE：启用回溯（默认值：1）

Docker设置

先决条件

• Docker已安装在您的系统上
• Docker Compose（通常包含在Docker桌面中）

配置

这 docker-compose.yaml 包括：

• 端口映射: 8085:8085
• 健康检查: curl http://localhost:8085/health
• 资源限制：512M内存，0.5 CPU
• 自动重启: unless-stopped
• 日志记录：带跟踪的结构化日志

使用Docker进行测试

# Build and start
docker-compose up --build

# Test health endpoint
curl http://localhost:8085/health

# Test content fetching
curl -X POST http://localhost:8085/api/fetch \
  -H "Content-Type: application/json" \
  -d '{"url": "https://httpbin.org/html"}'

项目结构

├── Cargo.toml              # Workspace configuration
├── domain/                 # Core business logic
│   ├── src/
│   │   ├── model/          # Domain models (content, request, response)
│   │   └── port/           # Interfaces for external dependencies
├── application/            # Business logic and use cases
│   ├── src/
│   │   ├── service/        # Application services
│   │   └── use_case/       # Use case implementations
├── infrastructure/        # External adapters
│   ├── src/
│   │   ├── client/         # HTTP client implementation
│   │   ├── adapter/        # HTML parser adapter
│   │   └── api/            # REST API server implementation
└── runner/                # Application entry point
    └── src/
        └── main.rs         # Main application with DI setup

发展

添加新功能

1. 在中定义域模型 domain/src/model/
2. 在中创建接口 domain/src/port/
3. 在中实现业务逻辑 application/src/service/ 或 application/src/use_case/
4. 在中创建基础结构适配器 infrastructure/src/
5. 导线依赖关系 runner/src/main.rs

API开发

要添加新端点，请执行以下操作：

1. 将请求/响应模型添加到 domain/src/model/request.rs
2. 在中实现业务逻辑 application/src/use_case/
3. 在中添加路由处理程序 infrastructure/src/api/server.rs
4. 在中更新路由器 create_router() 方法

测试

# Run all tests
cargo test

# Run tests for specific workspace member
cargo test -p domain
cargo test -p application
cargo test -p infrastructure

# Run specific test
cargo test test_name

# Integration tests with running server
cargo run --bin html-mcp-reader &
SERVER_PID=$!
curl http://localhost:8085/health
kill $SERVER_PID

错误处理

API返回适当的HTTP状态代码和错误响应：

HTTP状态代码

• 200 OK：请求成功
• 400 Bad Request：请求参数无效
• 500 Internal Server Error：服务器端错误

错误响应格式

{
  "error": "ERROR_CODE",
  "message": "Human-readable error description"
}

常见错误代码

• INVALID_URL：URL为空或格式错误
• FETCH_ERROR：网络、超时或HTTP错误
• PARSE_ERROR：HTML解析失败

日志记录

该应用程序使用不同级别的结构化日志记录：

• INFO：正常操作日志
• ERROR：错误条件
• DEBUG：详细的调试信息

使用配置日志记录 RUST_LOG 环境变量：

# Info level (default)
RUST_LOG=info cargo run

# Debug level for detailed logs
RUST_LOG=debug cargo run

# Module-specific logging
RUST_LOG=infrastructure::api::server=debug cargo run

演出

• 异步/等待：非阻塞I/O操作
• 连接池：HTTP客户端重用连接
• 内存效率高：流式HTML解析
• 资源限制：可配置的超时和内存限制
• Docker优化：多阶段构建，运行时映像最少

安全

• 非root用户：Docker容器以非root用户身份运行
• 资源限制：Docker Compose中的内存和CPU限制
• 输入验证：URL验证和参数净化
• 超时保护：可配置的请求超时
• CORS：跨源请求支持（可配置）

许可证

该项目是开源的，可在 MIT许可证.