docx-mcp

Instructions

Implementation Reference

• src/docx_mcp/server.py:211-256 (handler)

  The `list_docx` tool handler, which lists Word documents in a directory.

  def list_docx(directory: Optional[str] = None) -> dict[str, Any]:
      """
      List all Word documents in a directory.
  
      Args:
          directory: Directory path to list (defaults to project directory)
  
      Returns:
          Dictionary with list of documents
      """
      logger.info("Listing documents", extra={"tool": "list_docx", "directory": directory})
  
      try:
          if directory is None:
              dir_path = config.project_dir
          else:
              dir_path = normalize_path(directory)
  
          if not dir_path.is_dir():
              raise InvalidParameterError("directory", "Path is not a directory")
  
          documents = []
          for ext in [".docx", ".doc", ".dotx", ".dot"]:
              for file in dir_path.glob(f"**/*{ext}"):
                  try:
                      file_info = get_safe_file_info(str(file))
                      documents.append(file_info)
                  except Exception:
                      # Skip files that can't be accessed
                      continue
  
          logger.info(f"Found {len(documents)} documents", extra={"tool": "list_docx"})
  
          return {
              "status": "success",
              "directory": str(dir_path),
              "count": len(documents),
              "documents": documents,
          }
      except DocxMcpError as e:
          logger.warning(e.message, extra={"tool": "list_docx", "error_code": e.error_code})
          return {"status": "error", "error": e.message, "error_code": e.error_code}
      except Exception as e:
          logger.error(f"Unexpected error listing documents: {str(e)}")
          return {"status": "error", "error": str(e)}

• src/docx_mcp/server.py:210-256 (handler)

  The handler for the `list_docx` tool which scans a directory for various Word document file extensions and returns their metadata.

  @app.tool()
  def list_docx(directory: Optional[str] = None) -> dict[str, Any]:
      """
      List all Word documents in a directory.
  
      Args:
          directory: Directory path to list (defaults to project directory)
  
      Returns:
          Dictionary with list of documents
      """
      logger.info("Listing documents", extra={"tool": "list_docx", "directory": directory})
  
      try:
          if directory is None:
              dir_path = config.project_dir
          else:
              dir_path = normalize_path(directory)
  
          if not dir_path.is_dir():
              raise InvalidParameterError("directory", "Path is not a directory")
  
          documents = []
          for ext in [".docx", ".doc", ".dotx", ".dot"]:
              for file in dir_path.glob(f"**/*{ext}"):
                  try:
                      file_info = get_safe_file_info(str(file))
                      documents.append(file_info)
                  except Exception:
                      # Skip files that can't be accessed
                      continue
  
          logger.info(f"Found {len(documents)} documents", extra={"tool": "list_docx"})
  
          return {
              "status": "success",
              "directory": str(dir_path),
              "count": len(documents),
              "documents": documents,
          }
      except DocxMcpError as e:
          logger.warning(e.message, extra={"tool": "list_docx", "error_code": e.error_code})
          return {"status": "error", "error": e.message, "error_code": e.error_code}
      except Exception as e:
          logger.error(f"Unexpected error listing documents: {str(e)}")
          return {"status": "error", "error": str(e)}

• src/docx_mcp/server.py:210-211 (registration)

  The tool is registered using `@app.tool()` decorator on the `list_docx` function.

  @app.tool()
  def list_docx(directory: Optional[str] = None) -> dict[str, Any]: