wxauto MCP Server

Instructions

Implementation Reference

• src/wxauto_mcp/wxauto_mcp/api_sessions.py:111-167 (handler)

  The main handler function for filter_sessions tool. It filters sessions based on has_unread and ismute optional boolean parameters, returning a JSON formatted result with the filtered session list.

  @tool(
      name="filter_sessions",
      description="筛选会话列表。参数: has_unread (是否有未读), ismute (是否免打扰)"
  )
  def filter_sessions(
      has_unread: Optional[bool] = None,
      ismute: Optional[bool] = None
  ) -> str:
      """
      筛选会话列表
  
      Args:
          has_unread: 是否只显示有未读消息的会话
          ismute: 是否筛选免打扰会话
  
      Returns:
          JSON 格式的筛选结果
      """
      wrapper = _get_wrapper()
      if not wrapper:
          return format_result(False, "微信未初始化")
  
      try:
          sessions = wrapper.get_sessions()
          if not sessions:
              return format_result(True, "无会话数据", {"sessions": []})
  
          # 应用筛选
          filtered = sessions
          if has_unread is not None:
              if has_unread:
                  filtered = [s for s in filtered if s.new_count > 0]
              else:
                  filtered = [s for s in filtered if s.new_count == 0]
  
          if ismute is not None:
              filtered = [s for s in filtered if s.ismute == ismute]
  
          # 格式化结果
          formatted = []
          for session in filtered:
              formatted.append({
                  "name": session.name,
                  "time": session.time,
                  "content": session.content,
                  "new_count": session.new_count,
                  "ismute": session.ismute,
              })
  
          return format_result(
              True,
              f"筛选完成，共 {len(formatted)} 个会话",
              {"sessions": formatted}
          )
      except Exception as e:
          logger.error(f"筛选会话失败: {e}")
          return format_result(False, f"筛选会话失败: {e}")

• src/wxauto_mcp/wxauto_mcp/core/models.py:138-167 (schema)

  The SessionInfo dataclass schema that defines the structure of session objects, including fields for name, time, content, isnew, new_count (used for unread filtering), and ismute (used for mute filtering).

  @dataclass
  class SessionInfo:
      """
      会话信息模型
  
      Attributes:
          name: 聊天名称
          time: 最后消息时间
          content: 最后一条消息内容
          isnew: 是否是新会话
          new_count: 未读消息数
          ismute: 是否免打扰
      """
      name: str
      time: Optional[str] = None
      content: Optional[str] = None
      isnew: bool = False
      new_count: int = 0
      ismute: bool = False
  
      def to_dict(self) -> dict[str, Any]:
          """转换为字典"""
          return {
              "name": self.name,
              "time": self.time,
              "content": self.content,
              "isnew": self.isnew,
              "new_count": self.new_count,
              "ismute": self.ismute
          }

• src/wxauto_mcp/wxauto_mcp/rpc.py:51-80 (registration)

  The @tool decorator registration mechanism that registers filter_sessions as an MCP tool. It applies output limiting and registers the function to the TOOL_REGISTRY with its name and description.

  def tool(name: Optional[str] = None, description: Optional[str] = None) -> Callable:
      """
      工具装饰器
  
      注册函数为 MCP 工具，自动应用输出限制。
  
      Args:
          name: 工具名称，默认使用函数名
          description: 工具描述
  
      Returns:
          装饰后的函数
      """
  
      def decorator(func: Callable) -> Callable:
          # 应用输出限制
          limited_func = limit_output(func)
  
          # 注册到工具注册表
          tool_name = name or func.__name__
          TOOL_REGISTRY.register(
              name=tool_name,
              func=limited_func,
              description=description or func.__doc__ or "",
          )
  
          # 返回原函数，不修改其行为
          return func
  
      return decorator

• src/wxauto_mcp/wxauto_mcp/utils.py:14-31 (helper)

  Helper function used by filter_sessions to format the output as a JSON string with success status, message, and data fields containing the filtered sessions list.

  def format_result(success: bool, message: str, data: Optional[dict[str, Any]] = None) -> str:
      """
      格式化操作结果为 JSON 字符串
  
      Args:
          success: 操作是否成功
          message: 结果消息
          data: 附加数据
  
      Returns:
          JSON 格式的结果字符串
      """
      result = {
          "success": success,
          "message": message,
          "data": data or {},
      }
      return json.dumps(result, ensure_ascii=False, indent=2)