MCP Webpage Timestamps

🚀 MCP Webpage Timestamps

MCP Webpage Timestamps 是一款强大的 模型上下文协议 (MCP) 服务器，用于提取网页的创建、修改和发布时间戳。该工具专为网页抓取和网页内容的时间分析而设计。

🚀 快速开始

本项目可以通过多种方式进行安装和使用，以下为你详细介绍：

• Quick Install：

npm install -g mcp-webpage-timestamps

• Usage with npx：

npx mcp-webpage-timestamps

• Installing via Smithery：若要通过 Smithery 自动为 Claude Desktop 安装 mcp-webpage-timestamps，可使用以下命令：

npx -y @smithery/cli install @Fabien-desablens/mcp-webpage-timestamps --client claude

• Prerequisites：
  • Node.js 18.0.0 或更高版本
  • npm 或 yarn
• Development Install：

git clone https://github.com/Fabien-desablens/mcp-webpage-timestamps.git
cd mcp-webpage-timestamps
npm install
npm run build

✨ 主要特性

• 全面的时间戳提取：可从网页中提取创建、修改和发布时间戳。
• 多数据源支持：支持 HTML 元标签、HTTP 头、JSON-LD、微数据、OpenGraph、Twitter 卡片和启发式分析。
• 置信度评分：为提取的时间戳提供置信度级别（高/中/低）。
• 批量处理：可同时从多个 URL 提取时间戳。
• 可配置性：可自定义超时时间、用户代理、重定向处理和启发式选项。
• 生产就绪：具备强大的错误处理、全面的日志记录和 TypeScript 支持。

📦 安装指南

快速安装

npm install -g mcp-webpage-timestamps

使用 npx 安装

npx mcp-webpage-timestamps

通过 Smithery 安装

若要为 Claude Desktop 自动安装，可执行以下命令：

npx -y @smithery/cli install @Fabien-desablens/mcp-webpage-timestamps --client claude

开发环境安装

git clone https://github.com/Fabien-desablens/mcp-webpage-timestamps.git
cd mcp-webpage-timestamps
npm install
npm run build

💻 使用示例

基础用法

import { TimestampExtractor } from './src/extractor.js';

const extractor = new TimestampExtractor();
const result = await extractor.extractTimestamps('https://example.com/article');

console.log('Published:', result.publishedAt);
console.log('Modified:', result.modifiedAt);
console.log('Confidence:', result.confidence);
console.log('Sources:', result.sources.length);

高级用法

自定义配置

const extractor = new TimestampExtractor({
  timeout: 15000,
  userAgent: 'MyBot/1.0',
  enableHeuristics: false,
  maxRedirects: 3
});

const result = await extractor.extractTimestamps('https://example.com');

批量处理

const urls = [
  'https://example.com/article1',
  'https://example.com/article2',
  'https://example.com/article3'
];

const results = await Promise.all(
  urls.map(url => extractor.extractTimestamps(url))
);

📚 详细文档

作为 MCP 服务器使用

该服务器可与任何 MCP 兼容的客户端配合使用，以下是配置方法：

Claude Desktop 配置

在 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "webpage-timestamps": {
      "command": "npx",
      "args": ["mcp-webpage-timestamps"],
      "env": {}
    }
  }
}

客户端配置

在 MCP 设置中添加以下内容：

{
  "mcpServers": {
    "webpage-timestamps": {
      "command": "npx",
      "args": ["mcp-webpage-timestamps"]
    }
  }
}

直接使用

# 启动服务器
npm start

# 或在开发模式下运行
npm run dev

📚 API 文档

工具

extract_timestamps

从单个网页提取时间戳。 参数：

• url（字符串，必填）：要提取时间戳的网页 URL。
• config（对象，可选）：配置选项。 配置选项：
• timeout（数字）：请求超时时间（毫秒，默认值：10000）。
• userAgent（字符串）：请求的用户代理字符串。
• followRedirects（布尔值）：是否跟随 HTTP 重定向（默认值：true）。
• maxRedirects（数字）：最大重定向次数（默认值：5）。
• enableHeuristics（布尔值）：启用启发式时间戳检测（默认值：true）。 示例：

{
  "name": "extract_timestamps",
  "arguments": {
    "url": "https://example.com/article",
    "config": {
      "timeout": 15000,
      "enableHeuristics": true
    }
  }
}

batch_extract_timestamps

批量从多个网页提取时间戳。 参数：

• urls（字符串数组，必填）：要提取时间戳的 URL 数组。
• config（对象，可选）：与 extract_timestamps 相同的配置选项。 示例：

{
  "name": "batch_extract_timestamps",
  "arguments": {
    "urls": [
      "https://example.com/article1",
      "https://example.com/article2",
      "https://example.com/article3"
    ],
    "config": {
      "timeout": 10000
    }
  }
}

响应格式

两个工具都返回一个具有以下结构的 JSON 对象：

{
  url: string;
  createdAt?: Date;
  modifiedAt?: Date;
  publishedAt?: Date;
  sources: TimestampSource[];
  confidence: 'high' | 'medium' | 'low';
  errors?: string[];
}

TimestampSource：

{
  type: 'html-meta' | 'http-header' | 'json-ld' | 'microdata' | 'opengraph' | 'twitter' | 'heuristic';
  field: string;
  value: string;
  confidence: 'high' | 'medium' | 'low';
}

🔧 技术细节

支持的时间戳来源

HTML 元标签

• article:published_time
• article:modified_time
• date
• pubdate
• publishdate
• last-modified
• dc.date.created
• dc.date.modified
• dcterms.created
• dcterms.modified

HTTP 头

• Last-Modified
• Date

JSON-LD 结构化数据

• datePublished
• dateModified
• dateCreated

微数据

• datePublished
• dateModified

OpenGraph

• og:article:published_time
• og:article:modified_time
• og:updated_time

Twitter 卡片

• twitter:data1（包含日期信息时）

启发式分析

• 带有 datetime 属性的时间元素
• 文本中的常见日期模式
• 与日期相关的 CSS 类

开发脚本

# 热重载开发
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 以监视模式运行测试
npm run test:watch

# 代码检查
npm run lint

# 修复代码检查问题
npm run lint:fix

# 格式化代码
npm run format

测试

项目包含全面的测试：

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm test -- --coverage

# 运行特定测试文件
npm test -- extractor.test.ts

代码质量

• TypeScript：全面支持 TypeScript 并进行严格的类型检查。
• ESLint：使用推荐规则进行代码检查。
• Prettier：代码格式化。
• Jest：单元和集成测试。
• 95% 以上测试覆盖率：全面的测试套件。

⚙️ 使用场景

• 内容分析：分析网页内容的时间特征。
• 网页抓取：从抓取的页面中提取时间元数据。
• SEO 分析：分析发布和修改模式。
• 研究：研究网页内容的时间特征。
• 内容管理：跟踪内容的生命周期和更新。

⚠️ 错误处理

提取器能够优雅地处理各种错误情况：

• 网络错误：超时、连接被拒绝、DNS 解析失败。
• HTTP 错误：404、500 等 HTTP 状态码。
• 解析错误：无效的 HTML、格式错误的 JSON-LD、无法解析的日期。
• 配置错误：无效的 URL、超时值等。 所有错误都会捕获到响应的 errors 数组中，便于进行强大的错误处理和调试。

🤝 贡献指南

我们欢迎你的贡献！详细信息请参阅 贡献指南。

开发环境设置

1. 分叉仓库。
2. 克隆你的分叉：git clone https://github.com/Fabien-desablens/mcp-webpage-timestamps.git
3. 安装依赖：npm install
4. 创建分支：git checkout -b feature/your-feature
5. 进行更改。
6. 运行测试：npm test
7. 提交更改：git commit -m 'Add some feature'
8. 推送到分支：git push origin feature/your-feature
9. 提交拉取请求。

代码风格

• 遵循现有的代码风格。
• 所有新代码使用 TypeScript。
• 为新功能添加测试。
• 根据需要更新文档。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🛠️ 支持与反馈

• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• 文档参考：Wiki

📜 变更日志

详细的变更历史请参阅 CHANGELOG.md。

🙏 致谢

• 模型上下文协议 提供了出色的 MCP 框架。
• Cheerio 用于 HTML 解析。
• Axios 用于 HTTP 请求。
• date-fns 用于日期解析和操作。