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 用於日期解析和操作。