telegram_send_file

Instructions

        发送文件到 Telegram

        ⚠️ 使用场景（仅在必要时使用）：
        - 用户明确要求查看某个文件："查看 config.json"、"发送 main.py 给我"
        - 创建了重要的输出文件需要用户确认（如配置文件、报告等）
        - 生成了图表、图片等需要展示的文件
        - 需要用户下载某个文件进行后续操作

        ❌ 不要使用的场景：
        - 创建普通代码文件（用 telegram_notify 总结即可）
        - 修改了文件但不需要用户查看内容
        - 例行的文件操作

        优先级：
        1. 优先使用 telegram_notify 总结文件变更
        2. 如果用户明确要求，或确实需要查看，才发送文件
        3. 对于代码文件，如果只需要展示关键片段，优先使用 telegram_send_code

        参数：
        - file_path: 文件路径（相对于项目目录或绝对路径）
        - caption: 可选说明文字

        支持：
        - 文本文件、代码文件
        - 图片、PDF、文档等任意文件类型
        - 自动处理大文件

        示例：
        telegram_send_file(
            file_path="src/main.py",
            caption="修复后的主文件（用户要求查看）"
        )
        

Implementation Reference

• telegram_mcp_server/server.py:1139-1201 (handler)

  Main handler function for executing the telegram_send_file tool. Validates arguments, resolves file path relative to project, checks file existence, constructs caption, and sends the file as a document via Telegram Bot API's sendDocument endpoint using httpx.

  async def handle_telegram_send_file(session, arguments: dict) -> list[TextContent]:
      """Handle telegram_send_file tool"""
      file_path = arguments.get("file_path", "")
      caption = arguments.get("caption", "")
  
      if not file_path:
          return [TextContent(type="text", text="错误: file_path 参数不能为空")]
  
      # Resolve file path (relative to project or absolute)
      if not os.path.isabs(file_path):
          full_path = os.path.join(session.project_path, file_path)
      else:
          full_path = file_path
  
      # Check if file exists
      if not os.path.exists(full_path):
          return [TextContent(
              type="text",
              text=f"❌ 文件不存在: {file_path}"
          )]
  
      if not os.path.isfile(full_path):
          return [TextContent(
              type="text",
              text=f"❌ 不是文件（可能是目录）: {file_path}"
          )]
  
      # Build caption
      if not caption:
          caption = f"📄 [{session.session_id}] {file_path}"
      else:
          caption = f"📄 [{session.session_id}] {caption}"
  
      # Update session
      session.update_activity()
  
      # Send file to Telegram using HTTP API
      try:
          import httpx
  
          url = f"https://api.telegram.org/bot{config.TELEGRAM_BOT_TOKEN}/sendDocument"
  
          with open(full_path, 'rb') as f:
              files = {'document': (os.path.basename(file_path), f, 'application/octet-stream')}
              data = {
                  'chat_id': session.chat_id,
                  'caption': caption
              }
  
              async with httpx.AsyncClient() as client:
                  response = await client.post(url, files=files, data=data, timeout=60.0)
                  response.raise_for_status()
  
          return [TextContent(
              type="text",
              text=f"✅ 已发送文件到 Telegram (会话: {session.session_id}, 文件: {file_path})"
          )]
      except Exception as e:
          return [TextContent(
              type="text",
              text=f"❌ 发送文件失败: {str(e)}"
          )]

• telegram_mcp_server/server.py:446-496 (registration)

  Tool registration in the list_tools() handler, defining the name, description, and inputSchema for the telegram_send_file tool.

  Tool(
      name="telegram_send_file",
      description="""
      发送文件到 Telegram
  
      ⚠️ 使用场景（仅在必要时使用）：
      - 用户明确要求查看某个文件："查看 config.json"、"发送 main.py 给我"
      - 创建了重要的输出文件需要用户确认（如配置文件、报告等）
      - 生成了图表、图片等需要展示的文件
      - 需要用户下载某个文件进行后续操作
  
      ❌ 不要使用的场景：
      - 创建普通代码文件（用 telegram_notify 总结即可）
      - 修改了文件但不需要用户查看内容
      - 例行的文件操作
  
      优先级：
      1. 优先使用 telegram_notify 总结文件变更
      2. 如果用户明确要求，或确实需要查看，才发送文件
      3. 对于代码文件，如果只需要展示关键片段，优先使用 telegram_send_code
  
      参数：
      - file_path: 文件路径（相对于项目目录或绝对路径）
      - caption: 可选说明文字
  
      支持：
      - 文本文件、代码文件
      - 图片、PDF、文档等任意文件类型
      - 自动处理大文件
  
      示例：
      telegram_send_file(
          file_path="src/main.py",
          caption="修复后的主文件（用户要求查看）"
      )
      """,
      inputSchema={
          "type": "object",
          "properties": {
              "file_path": {
                  "type": "string",
                  "description": "文件路径"
              },
              "caption": {
                  "type": "string",
                  "description": "可选说明文字"
              }
          },
          "required": ["file_path"]
      }
  ),

• telegram_mcp_server/server.py:482-495 (schema)

  Input schema defining parameters: file_path (required string), caption (optional string).

  inputSchema={
      "type": "object",
      "properties": {
          "file_path": {
              "type": "string",
              "description": "文件路径"
          },
          "caption": {
              "type": "string",
              "description": "可选说明文字"
          }
      },
      "required": ["file_path"]
  }

• telegram_mcp_server/server.py:683-684 (registration)

  Dispatch logic in call_tool() that routes calls to the specific handler based on tool name.

  elif name == "telegram_send_file":
      return await handle_telegram_send_file(session, arguments)