Agenticledger MCP Chatscrapper

聊天爬虫MCP服务器

版本： 1.0.0 平台： AgentLedger人工智能代理平台 状态： 生产就绪

概述

ChatScraper是一个MCP（模型上下文协议）服务器，它使AI代理能够抓取和分析来自Telegram频道/组和Slack频道的消息。它提供对聊天历史的过滤访问，支持日期范围、关键字匹配、用户过滤和媒体检测。

用例

• 上下文收集： AI代理检索聊天历史以获取上下文
• 趋势分析： 随着时间的推移监控特定的关键字或主题
• 社区见解： 分析公共渠道中的讨论
• 研究： 从聊天社区提取信息
• 顺从： 审计和审查小组沟通

身份验证模式

此MCP服务器根据平台使用两种不同的身份验证模式：

电报-基于形式的模式（复合令牌）

令牌格式：

api_id:api_hash:phone:session_string

例子：

123456:abcd1234567890:+1234567890:base64_encoded_session_data

组件：

• api_id：来自的电报API IDhttps://my.telegram.org
• api_hash：来自的电报API哈希https://my.telegram.org
• phone：带国家代码的电话号码（例如+1234567890）
• session_string：Base64编码会话数据（登录后生成）

平台职责：

1. 收集 api_id, api_hash，以及 phone 来自用户
2. 处理初始Telegram登录流程（短信代码+可选2FA）
3. 使用Telethon生成会话字符串 StringSession
4. 创建复合令牌并安全存储
5. 向MCP服务器提供令牌

MCP服务器职责：

• 解析复合令牌
• 从会话字符串重新创建Telethon会话
• 进行经过身份验证的API调用
• 每个请求不需要重新身份验证

______________________________________________________________________

Slack-OAuth模式（直接令牌）

令牌格式：

xoxb-1234567890-ABCDEFGHIJ  (Bot token)
xoxp-1234567890-ABCDEFGHIJ  (User token)

所需的OAuth范围：

• channels:history -阅读公共频道消息
• groups:history -阅读私人频道消息
• channels:read -列出公共频道
• groups:read -列出私人频道
• files:read -访问文件元数据和URL
• users:read -获取用户信息

平台职责：

1. 处理Slack OAuth流
2. 安全地存储令牌
3. 将令牌直接传递给MCP服务器

MCP服务器职责：

• 使用带有@lack/web-api SDK的令牌
• 进行经过身份验证的API调用
• 处理速率限制和错误

______________________________________________________________________

可用工具

1.scrape_telegram_channel

说明： 使用高级过滤选项从Telegram频道或群组导出消息。

参数：

请求示例：

{
  "accessToken": "123456:hash:+1234567890:session",
  "chat": "@publicchannel",
  "limit": 50,
  "minDate": "2025-01-01",
  "maxDate": "2025-01-20",
  "keywords": "blockchain,crypto",
  "reverse": true
}

示例响应：

{
  "success": true,
  "data": {
    "channel": "@publicchannel",
    "totalMessages": 50,
    "messages": [
      {
        "id": 123,
        "date": "2025-01-15T10:30:00Z",
        "text": "Blockchain technology is revolutionary...",
        "sender": "username",
        "senderId": 456789,
        "mediaType": null,
        "mediaUrl": null,
        "reactions": { "👍": 5, "🔥": 3 },
        "views": 1234,
        "forwards": 10
      }
    ],
    "metadata": {
      "chatTitle": "Public Channel",
      "chatType": "channel",
      "totalParticipants": 5000,
      "exportedAt": "2025-01-20T12:00:00Z"
    }
  }
}

______________________________________________________________________

2.列表_电报_频道

说明： 列出经过身份验证的用户可访问的所有Telegram频道和组。

参数：

请求示例：

{
  "accessToken": "123456:hash:+1234567890:session"
}

示例响应：

{
  "success": true,
  "data": {
    "channels": [
      {
        "id": -1001234567890,
        "title": "Public Channel",
        "username": "@publicchannel",
        "type": "channel",
        "participants": 5000,
        "isPublic": true,
        "description": "Channel description"
      },
      {
        "id": -1009876543210,
        "title": "Private Group",
        "username": null,
        "type": "group",
        "participants": 250,
        "isPublic": false
      }
    ],
    "totalCount": 2
  }
}

______________________________________________________________________

3.scrape_slack_channel

说明： 通过过滤和可选线程支持从Slack频道导出消息。

参数：

请求示例：

{
  "accessToken": "xoxb-1234567890-ABCDEFGHIJ",
  "channel": "#general",
  "limit": 30,
  "minDate": "2025-01-10",
  "keywords": "deployment,production",
  "includeThreads": true
}

示例响应：

{
  "success": true,
  "data": {
    "channel": "#general",
    "totalMessages": 30,
    "messages": [
      {
        "ts": "1705752000.123456",
        "date": "2025-01-20T10:00:00Z",
        "text": "Production deployment completed successfully!",
        "user": "U012345",
        "userName": "john.doe",
        "userRealName": "John Doe",
        "files": [
          {
            "id": "F0123456",
            "name": "deployment.log",
            "mimetype": "text/plain",
            "size": 2048,
            "url": "https://files.slack.com/..."
          }
        ],
        "reactions": [
          {
            "name": "tada",
            "count": 5,
            "users": ["U012345", "U067890"]
          }
        ],
        "threadTs": "1705752000.123456",
        "replyCount": 3
      }
    ],
    "metadata": {
      "channelName": "general",
      "channelId": "C0123456789",
      "workspace": "MyWorkspace",
      "exportedAt": "2025-01-20T12:00:00Z"
    }
  }
}

______________________________________________________________________

4.list_slack_channels

说明： 列出机器人或用户令牌可访问的所有Slack频道。

参数：

请求示例：

{
  "accessToken": "xoxb-1234567890-ABCDEFGHIJ",
  "includePrivate": true
}

示例响应：

{
  "success": true,
  "data": {
    "channels": [
      {
        "id": "C0123456789",
        "name": "general",
        "isPrivate": false,
        "memberCount": 50,
        "topic": "General discussion",
        "purpose": "Company-wide announcements",
        "created": 1609459200
      },
      {
        "id": "G9876543210",
        "name": "engineering",
        "isPrivate": true,
        "memberCount": 15,
        "topic": "Engineering team chat",
        "created": 1640995200
      }
    ],
    "totalCount": 2
  }
}

______________________________________________________________________

安装

先决条件

• Node.js 18.0.0或更高版本
• npm或纱线

再进行

cd chatscraper
npm install

构建

npm run build

这将TypeScript编译为JavaScript dist/ 目录。

______________________________________________________________________

测试

运行所有测试

npm test

仅运行集成测试

npm run test:integration

注： 集成测试需要有效的API凭据。看 tests/ 测试设置说明目录。

______________________________________________________________________

发展

观看模式

npm run dev

这将在监视模式下运行TypeScript，并在文件更改时自动重新编译。

代码检查

npm run lint

______________________________________________________________________

错误处理

所有工具都返回标准化的响应格式：

成功响应：

{
  "success": true,
  "data": { ... }
}

错误响应：

{
  "success": false,
  "error": "Descriptive error message",
  "retryAfter": 60  // Optional, for rate limit errors
}

常见错误

电报：

• Invalid or expired session -需要重新验证
• Rate limited by Telegram -等待并重试（提供后重试）
• Channel not found -检查频道访问/权限
• Invalid Telegram token format -检查令牌结构

松弛：

• Invalid Slack token -检查令牌有效性
• Token expired or revoked -需要重新验证
• Rate limited by Slack -等待并重试（提供后重试）
• Channel not found -确保机器人是渠道成员
• Missing permissions -添加所需的OAuth作用域

______________________________________________________________________

速率限制

电报

• 因账户类型而异（普通账户与高级账户）
• FloodWaitError返回等待时间
• 自动处理，错误信息清晰

Slack

• 免费等级： 每种方法每分钟约1个请求
• 专业级别： 每分钟约100个请求
• 429条回复： 在标头后包含重试
• 错误包括 retryAfter 领域

______________________________________________________________________

平台集成说明

会话管理（电报）

平台必须处理Telegram的交互式登录流程：

1. 收集 api_id, api_hash, phone 来自用户
2. 启动Telethon会话
3. 向用户请求短信代码
4. 可选择请求2FA密码
5. 生成会话字符串： client.session.save()
6. 创建复合令牌： ${apiId}:${apiHash}:${phone}:${sessionString}
7. 安全地存储令牌

平台侧代码示例：

import { TelegramClient } from 'telegram';
import { StringSession } from 'telegram/sessions';

const stringSession = new StringSession(''); // Empty for new login
const client = new TelegramClient(stringSession, apiId, apiHash, {});

await client.start({
  phoneNumber: async () => userPhone,
  password: async () => user2FA,  // Optional
  phoneCode: async () => smsCode,
  onError: (err) => console.error(err)
});

const sessionString = client.session.save();
const compositeToken = `${apiId}:${apiHash}:${phone}:${sessionString}`;
// Store compositeToken for user

OAuth流（Slack）

标准Slack OAuth 2.0流程。平台手柄：

1. 将用户重定向到Slack OAuth URL
2. 接收授权码
3. 访问令牌的交换代码
4. 安全地存储令牌
5. 将令牌传递给MCP服务器

______________________________________________________________________

演出

典型响应时间：

• 电报抓取（100条消息）：1-3秒
• 松弛抓取（100条消息）：2-4秒
• 列出频道：\<1秒

限制：

• 每个请求最多1000条消息（防止超时）
• 未实现分页（使用日期范围多次调用）
• 不支持媒体下载（仅提供URL）

______________________________________________________________________

安全注意事项

• 从不记录凭据 -从所有日志中排除的令牌
• 验证所有输入 -Zod模式强制类型
• 会话隔离 -每个请求都会创建新的scraper实例
• 自动清理 -Telegram客户端在使用后断开连接
• 令牌验证 -API调用前检查的格式

______________________________________________________________________

已知限制

1. 无媒体下载： 提供的是媒体URL，而不是文件内容
2. 无分页光标： 对大型导出使用日期范围
3. 线程限制： 限制松弛线程以避免深度递归
4. 仅限公众访问（电报）： 用户必须具有频道访问权限
5. 需要Bot会员资格（Slack）： Bot必须在通道中

______________________________________________________________________

未来的增强功能

• \[\]媒体文件下载支持
• \[\]基于光标的分页
• \[\]集成不一致
• \[\]导出为不同格式（CSV、Markdown）
• \[\]高级过滤（正则表达式、情感）
• \[\]流式传输大型结果集
• \[\]缓存频繁访问的频道

______________________________________________________________________

支持

问题： GitHub存储库上的文件问题

问题： 联系代理分类账支持

______________________________________________________________________

许可证

MIT许可证

______________________________________________________________________

致谢

• 专为 代理分类账 AI代理平台
• 用途 Telegram SDK 用于Telegram集成
• 用途 @slack/web api 用于Slack集成
• 跟随 MCP协议 规格

______________________________________________________________________

已准备好集成AgentLedger平台 🚀