Telegram MCP Server

Instructions

        获取并发送当前会话的上下文信息到 Telegram

        ⚠️ 重要：调用此工具时，你应该：
        1. 检查系统提供的 token 使用量信息（<budget:token_budget> 标签）
        2. 将 token 使用情况包含在发送的信息中
        3. 发送完整的上下文信息（会话信息 + token 使用情况）

        返回信息应包括：
        - 会话 ID 和项目路径
        - Token 使用量（已使用 / 总量 / 剩余 / 使用率）
        - 会话运行时间
        - 系统信息
        - Telegram 配置

        示例输出格式：
        📊 会话上下文信息
        🆔 会话: testtg
        📁 项目: /path/to/project

        💾 Token 使用:
        - 已使用: 41,853 tokens
        - 总容量: 1,000,000 tokens
        - 剩余: 958,147 tokens
        - 使用率: 4.2%

        ⏱️ 运行时间: 15 分钟
        🖥️ 系统: Darwin 24.6.0
        🐍 Python: 3.14.0
        

Implementation Reference

• telegram_mcp_server/server.py:1060-1137 (handler)

  The handler function that implements the tool logic: gathers comprehensive session context (ID, paths, token usage if provided, timing, system info, Telegram config), formats it as a Markdown message, sends it to Telegram, and returns success/error feedback.

  async def handle_telegram_get_context_info(session, arguments: dict) -> list[TextContent]:
      """Handle telegram_get_context_info tool"""
      import platform
      from datetime import datetime
  
      token_used = arguments.get("token_used", 0)
      token_total = arguments.get("token_total", 1000000)
  
      # Gather context information
      info_parts = []
  
      info_parts.append("📊 会话上下文信息")
      info_parts.append("━━━━━━━━━━━━━━━━")
      info_parts.append(f"🆔 会话 ID: {session.session_id}")
      info_parts.append(f"📁 项目路径: {session.project_path}")
      info_parts.append(f"📂 当前目录: {os.getcwd()}")
  
      # Token usage (if provided)
      if token_used > 0:
          token_remaining = token_total - token_used
          usage_percent = (token_used / token_total) * 100
  
          info_parts.append("")
          info_parts.append("💾 Token 使用情况:")
          info_parts.append(f"- 已使用: {token_used:,} tokens")
          info_parts.append(f"- 总容量: {token_total:,} tokens")
          info_parts.append(f"- 剩余: {token_remaining:,} tokens")
          info_parts.append(f"- 使用率: {usage_percent:.1f}%")
  
      # Session timing
      created = datetime.fromisoformat(session.created_at)
      last_active = datetime.fromisoformat(session.last_active)
      uptime = (datetime.now() - created).total_seconds()
  
      info_parts.append("")
      info_parts.append("⏱️  会话时间:")
      info_parts.append(f"- 创建时间: {created.strftime('%Y-%m-%d %H:%M:%S')}")
  
      if uptime < 60:
          info_parts.append(f"- 运行时长: {int(uptime)} 秒")
      elif uptime < 3600:
          info_parts.append(f"- 运行时长: {int(uptime / 60)} 分钟")
      elif uptime < 86400:
          info_parts.append(f"- 运行时长: {int(uptime / 3600)} 小时")
      else:
          info_parts.append(f"- 运行时长: {int(uptime / 86400)} 天")
  
      # System info
      info_parts.append("")
      info_parts.append("🖥️  系统环境:")
      info_parts.append(f"- 操作系统: {platform.system()} {platform.release()}")
      info_parts.append(f"- Python: {platform.python_version()}")
      info_parts.append(f"- 状态: {session.status}")
  
      # Telegram config
      info_parts.append("")
      info_parts.append("📱 Telegram 配置:")
      info_parts.append(f"- 最长等待: {config.TELEGRAM_MAX_WAIT // 86400} 天")
      info_parts.append(f"- 轮询: {config.POLL_INTERVALS[0]}s → {config.POLL_INTERVALS[1]}s → {config.POLL_INTERVALS[2]}s")
  
      message = "\n".join(info_parts)
  
      # Update session
      session.update_activity()
  
      # Send to Telegram
      try:
          await send_telegram_message(session.chat_id, message)
          return [TextContent(
              type="text",
              text=f"✅ 上下文信息已发送到 Telegram (会话: {session.session_id})\n\n💡 提示：下次调用时传入 token_used 参数可显示 token 使用量"
          )]
      except Exception as e:
          return [TextContent(
              type="text",
              text=f"❌ 发送失败: {str(e)}"
          )]

• telegram_mcp_server/server.py:497-543 (registration)

  Tool registration in the list_tools() handler, including name, detailed description of usage and expected output format, and inputSchema defining optional token_used and token_total parameters.

  Tool(
      name="telegram_get_context_info",
      description="""
      获取并发送当前会话的上下文信息到 Telegram
  
      ⚠️ 重要：调用此工具时，你应该：
      1. 检查系统提供的 token 使用量信息（<budget:token_budget> 标签）
      2. 将 token 使用情况包含在发送的信息中
      3. 发送完整的上下文信息（会话信息 + token 使用情况）
  
      返回信息应包括：
      - 会话 ID 和项目路径
      - Token 使用量（已使用 / 总量 / 剩余 / 使用率）
      - 会话运行时间
      - 系统信息
      - Telegram 配置
  
      示例输出格式：
      📊 会话上下文信息
      🆔 会话: testtg
      📁 项目: /path/to/project
  
      💾 Token 使用:
      - 已使用: 41,853 tokens
      - 总容量: 1,000,000 tokens
      - 剩余: 958,147 tokens
      - 使用率: 4.2%
  
      ⏱️ 运行时间: 15 分钟
      🖥️ 系统: Darwin 24.6.0
      🐍 Python: 3.14.0
      """,
      inputSchema={
          "type": "object",
          "properties": {
              "token_used": {
                  "type": "integer",
                  "description": "已使用的 token 数量（从系统预算信息中获取）"
              },
              "token_total": {
                  "type": "integer",
                  "description": "总 token 容量（从系统预算信息中获取）",
                  "default": 1000000
              }
          }
      }
  ),

• telegram_mcp_server/server.py:685-686 (registration)

  Dispatch logic in the main @server.call_tool() function that routes calls to the specific handler.

  elif name == "telegram_get_context_info":
      return await handle_telegram_get_context_info(session, arguments)

• telegram_mcp_server/server.py:529-542 (schema)

  Input schema defining the parameters for the tool: token_used (integer, required for usage display) and token_total (integer, default 1M).

  inputSchema={
      "type": "object",
      "properties": {
          "token_used": {
              "type": "integer",
              "description": "已使用的 token 数量（从系统预算信息中获取）"
          },
          "token_total": {
              "type": "integer",
              "description": "总 token 容量（从系统预算信息中获取）",
              "default": 1000000
          }
      }
  }